claude-code-session-manager 0.52.0 → 0.53.0

package/dist/index.html

@@ -7,10 +7,10 @@
     <link rel="preconnect" href="https://fonts.googleapis.com">
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
     <link href="https://fonts.googleapis.com/css2?family=Newsreader:ital,opsz,wght@0,6..72,400;0,6..72,500;0,6..72,600;0,6..72,700;1,6..72,400&family=Geist:wght@300;400;500;600;700&family=IBM+Plex+Mono:wght@400;500;600&display=swap" rel="stylesheet">
-    <script type="module" crossorigin src="./assets/index-hNso_ykJ.js"></script>
+    <script type="module" crossorigin src="./assets/index-D1v4VU6k.js"></script>
     <link rel="modulepreload" crossorigin href="./assets/monaco-editor-BW5C4Iv1.js">
     <link rel="stylesheet" crossorigin href="./assets/monaco-editor-BTnBOi8r.css">
-    <link rel="stylesheet" crossorigin href="./assets/index-CKP60_3d.css">
+    <link rel="stylesheet" crossorigin href="./assets/index-BoOiJJOr.css">
   </head>
   <body class="bg-bg text-fg font-sans antialiased">
     <div id="root"></div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-session-manager",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "description": "Local cockpit for the Claude Code CLI — multi-tab terminal, full config surface, scheduler, voice dictation, and live observability.",
   "type": "module",
   "main": "src/main/index.cjs",

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

@@ -200,6 +200,116 @@ test('findJoinableEpic falls through to the similarity check when preferEpicId p
   expect(joined).toEqual({ epicId: sibling.epicId, matchedBy: 'similarity', score: expect.any(Number) });
 });
 
+test('ensureEpic mints with status "proposed" by default', async () => {
+  const cwd = await mkCwd();
+
+  const minted = await ensureEpic(cwd, { goalText: 'default status epic' });
+
+  const index = readActiveIndex(cwd);
+  expect(index.sessions[minted.epicId].status).toBe('proposed');
+});
+
+test('ensureEpic throws when a mint is requested with status "active" (born-proposed law), and appends an audit event', async () => {
+  const cwd = await mkCwd();
+  const auditLog = require('../lib/auditLog.cjs');
+
+  await expect(
+    ensureEpic(cwd, { goalText: 'should never mint active', status: 'active' }),
+  ).rejects.toThrow(/born 'proposed'/);
+
+  const index = readActiveIndex(cwd);
+  expect(Object.keys(index.sessions)).toHaveLength(0);
+
+  const records = fs.readFileSync(auditLog.AUDIT_LOG_PATH, 'utf8')
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => JSON.parse(line))
+    .filter((r) => r.cwd === cwd);
+  expect(records).toHaveLength(1);
+  expect(records[0].kind).toBe('epic_mint_refused');
+  expect(records[0].status).toBe('active');
+});
+
+test('ensureEpic still joins an existing active Epic via preferEpicId even when status:"active" is requested', async () => {
+  const cwd = await mkCwd();
+  const first = await ensureEpic(cwd, { goalText: 'already running epic' });
+  const index = readActiveIndex(cwd);
+  index.sessions[first.epicId].status = 'active';
+  fs.writeFileSync(
+    path.join(cwd, 'session-manager-operations', 'prompt-sessions', 'active-index.json'),
+    JSON.stringify(index, null, 2),
+  );
+
+  const second = await ensureEpic(cwd, { goalText: 'unrelated text', epicId: first.epicId, status: 'active' });
+
+  expect(second.created).toBe(false);
+  expect(second.epicId).toBe(first.epicId);
+});
+
+test('ensureEpic falls through to a "proposed" mint when explicit epicId is archived/completed, never throwing', async () => {
+  const cwd = await mkCwd();
+  const first = await ensureEpic(cwd, { goalText: 'completed epic' });
+  const index = readActiveIndex(cwd);
+  index.sessions[first.epicId].status = 'completed';
+  fs.writeFileSync(
+    path.join(cwd, 'session-manager-operations', 'prompt-sessions', 'active-index.json'),
+    JSON.stringify(index, null, 2),
+  );
+
+  const second = await ensureEpic(cwd, { goalText: 'totally unrelated goal text here', epicId: first.epicId });
+
+  expect(second.created).toBe(true);
+  expect(second.epicId).not.toBe(first.epicId);
+  const after = readActiveIndex(cwd);
+  expect(after.sessions[second.epicId].status).toBe('proposed');
+});
+
+function readAuditRecordsForCwd(auditLog, cwd) {
+  if (!fs.existsSync(auditLog.AUDIT_LOG_PATH)) return [];
+  return fs.readFileSync(auditLog.AUDIT_LOG_PATH, 'utf8')
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter((record) => record && record.cwd === cwd);
+}
+
+test('mintIfMissing:false refusal appends an epic_mint_refused audit event', async () => {
+  const cwd = await mkCwd();
+  const auditLog = require('../lib/auditLog.cjs');
+
+  await expect(ensureEpic(cwd, { goalText: 'no epic yet', mintIfMissing: false })).rejects.toThrow();
+
+  const records = readAuditRecordsForCwd(auditLog, cwd);
+  expect(records).toHaveLength(1);
+  expect(records[0].kind).toBe('epic_mint_refused');
+  expect(records[0].cwd).toBe(cwd);
+});
+
+test('not-open explicit-epicId fall-through appends an epic_mint_refused audit event', async () => {
+  const cwd = await mkCwd();
+  const first = await ensureEpic(cwd, { goalText: 'to be completed' });
+  const index = readActiveIndex(cwd);
+  index.sessions[first.epicId].status = 'completed';
+  fs.writeFileSync(
+    path.join(cwd, 'session-manager-operations', 'prompt-sessions', 'active-index.json'),
+    JSON.stringify(index, null, 2),
+  );
+  const auditLog = require('../lib/auditLog.cjs');
+
+  await ensureEpic(cwd, { goalText: 'unrelated fresh goal xyz', epicId: first.epicId });
+
+  const records = readAuditRecordsForCwd(auditLog, cwd);
+  const refusal = records.find((r) => r.kind === 'epic_mint_refused');
+  expect(refusal).toBeDefined();
+  expect(refusal.epicId).toBe(first.epicId);
+});
+
 test('ensureEpic with forceNewEpic:true mints even when a near-identical open Epic exists', async () => {
   const cwd = await mkCwd();
 

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

@@ -532,6 +532,11 @@ test('resolveSourcePromptIdFromClaudeSession finds the Epic whose claudeSessionI
   }
 });
 
+// Real-homedir-rooted like the chat-only-epic test above (see its comment at
+// line ~449): validatePath's read boundary is home-dir-wide, and this
+// exercises createPrd's real config.addAllowedRoot/writeTextAtomic path. Safe
+// because the random suffix is never a registered project the live scheduler
+// scans for PRDs, and it's removed in `finally`.
 test('createPrd resolves sourcePromptId from originClaudeSessionId when the caller omitted sourcePromptId', async () => {
   const root = await fsp.mkdtemp(path.join(os.homedir(), '.sm-origin-session-epic-'));
   config.addAllowedRoot(root);
@@ -555,6 +560,7 @@ test('createPrd resolves sourcePromptId from originClaudeSessionId when the call
   }
 });
 
+// Same real-homedir rationale as the two tests above.
 test('createPrd leaves sourcePromptId unset when originClaudeSessionId matches no known Epic (plain SessionTab chat)', async () => {
   const root = await fsp.mkdtemp(path.join(os.homedir(), '.sm-origin-session-no-match-'));
   config.addAllowedRoot(root);

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

@@ -105,6 +105,11 @@ test('migratePrds ignores non-.md and dotfiles, and no-ops on a missing legacy d
 
 test('migratePrds expands a tilde-prefixed cwd and moves the file', async () => {
   const legacyDir = await mkLegacyDir();
+  // Deliberately rooted under the REAL os.homedir() (not os.tmpdir()) — the
+  // assertion under test is tilde-expansion relative to the actual home dir,
+  // so a real homedir path is load-bearing here, not incidental. Still safe:
+  // the random suffix is never a registered project the live scheduler scans
+  // for PRDs, and it's removed in afterEach via tmpDirs/fsp.rm.
   const projectCwd = await fsp.mkdtemp(path.join(os.homedir(), '.sm-prdmigration-tilde-'));
   tmpDirs.push(projectCwd);
   const tildeCwd = path.join('~', path.relative(os.homedir(), projectCwd));

package/src/main/__tests__/scheduler-find-prd-dir.test.cjs

@@ -6,20 +6,53 @@
  * `<cwd>/session-manager-operations/scheduler/prds/`) must still resolve,
  * since findPrdDir's candidatePrdsDirs() searches the legacy dir first.
  *
- * Touches the real legacy PRDS_DIR (scheduler.cjs hard-codes it from
- * os.homedir(), same as other scheduler unit tests that exercise
- * global-path-backed exports) with a unique slug, and cleans up after itself.
+ * HOME-isolated (PRD 812 incident fix): scheduler.cjs derives PRDS_DIR from
+ * os.homedir() at module load. This test used to write straight into the
+ * REAL `~/.claude/session-manager/scheduled-plans/prds/` — the live
+ * scheduler's `reconcile()` scans that dir every 60s and enqueued the
+ * fixture as a phantom job (job 812-test-legacy-only-1975929-233060) before
+ * this test's own cleanup ran. Now HOME is stubbed to a mkdtemp dir BEFORE
+ * scheduler.cjs is first required, so PRDS_DIR resolves under the temp dir
+ * and nothing here can reach the real scheduler root. The
+ * `PRDS_DIR.startsWith(tmpHome)` guard is the regression test for that
+ * incident: if module-load ordering ever changes so the real homedir gets
+ * snapshotted first, this throws loudly instead of silently poisoning the
+ * live queue again.
  *
  * Run: timeout 120 npx vitest run src/main/__tests__/scheduler-find-prd-dir.test.cjs
  */
 
 'use strict';
 
-import { test, expect } from 'vitest';
+import { test, expect, beforeAll, afterAll } from 'vitest';
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
-const { findPrdDir, PRDS_DIR } = require('../scheduler.cjs');
+
+let tmpHome;
+let originalHome;
+let findPrdDir;
+let PRDS_DIR;
+
+beforeAll(() => {
+  originalHome = process.env.HOME;
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-find-prd-dir-'));
+  process.env.HOME = tmpHome;
+
+  // Load AFTER HOME is stubbed — scheduler.cjs snapshots os.homedir() into
+  // PRDS_DIR at module load, not lazily.
+  ({ findPrdDir, PRDS_DIR } = require('../scheduler.cjs'));
+
+  // Hard guard: never let this test write into the real scheduler root.
+  if (!PRDS_DIR.startsWith(tmpHome)) {
+    throw new Error(`refusing to run: PRDS_DIR (${PRDS_DIR}) is not under the temp HOME (${tmpHome})`);
+  }
+});
+
+afterAll(() => {
+  process.env.HOME = originalHome;
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
 
 test('findPrdDir resolves a slug that exists only in the legacy global PRDs dir', async () => {
   const slug = `812-test-legacy-only-${process.pid}-${Math.floor(Math.random() * 1e6)}`;

package/src/main/__tests__/scheduler-prd-missing-skip.test.cjs

@@ -0,0 +1,89 @@
+/**
+ * scheduler-prd-missing-skip.test.cjs — regression test for PRD 812's
+ * failure-classification fix: a queued job whose PRD source has disappeared
+ * between enqueue and dispatch (e.g. a test fixture that leaked into the
+ * live queue and was cleaned up before the job ran) must be retired as a
+ * stale row (exitCode: 0, skipped: 'prd-missing'), not treated as a hard
+ * job failure (exitCode: -1). A genuinely unreadable/unparseable PRD (a
+ * real, non-ENOENT error) must still fail with exitCode: -1.
+ *
+ * HOME-isolated per the same incident: stub HOME to a mkdtemp dir before
+ * requiring scheduler.cjs, and never write into the real scheduler root.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/scheduler-prd-missing-skip.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeAll, afterAll } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+let tmpHome;
+let originalHome;
+let executeJob;
+let PRDS_DIR;
+
+beforeAll(() => {
+  originalHome = process.env.HOME;
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-prd-missing-skip-'));
+  process.env.HOME = tmpHome;
+
+  ({ executeJob, PRDS_DIR } = require('../scheduler.cjs'));
+
+  if (!PRDS_DIR.startsWith(tmpHome)) {
+    throw new Error(`refusing to run: PRDS_DIR (${PRDS_DIR}) is not under the temp HOME (${tmpHome})`);
+  }
+});
+
+afterAll(() => {
+  process.env.HOME = originalHome;
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+
+test('a job whose PRD source is gone everywhere is retired, not failed', async () => {
+  const projectCwd = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-prd-missing-project-'));
+  // config.cjs's writeJsonSync (used for the job's meta.json) restricts
+  // writes to WRITE_PREFIXES, which includes `<home>/.claude` — so runDir
+  // must live under the stubbed tmpHome's .claude/, not the system tmpdir.
+  fs.mkdirSync(path.join(tmpHome, '.claude'), { recursive: true });
+  const runDir = fs.mkdtempSync(path.join(tmpHome, '.claude', 'sm-prd-missing-run-'));
+  try {
+    const slug = `812-test-missing-${process.pid}-${Math.floor(Math.random() * 1e6)}`;
+    const job = { slug, cwd: projectCwd };
+
+    const result = await executeJob(job, runDir, projectCwd, () => {});
+
+    expect(result.exitCode).toBe(0);
+    expect(result.skipped).toBe('prd-missing');
+  } finally {
+    fs.rmSync(projectCwd, { recursive: true, force: true });
+    fs.rmSync(runDir, { recursive: true, force: true });
+  }
+});
+
+test('a job whose PRD source exists but is unreadable for a non-ENOENT reason still fails', async () => {
+  const projectCwd = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-prd-toobig-project-'));
+  fs.mkdirSync(path.join(tmpHome, '.claude'), { recursive: true });
+  const runDir = fs.mkdtempSync(path.join(tmpHome, '.claude', 'sm-prd-toobig-run-'));
+  try {
+    const slug = `812-test-toobig-${process.pid}-${Math.floor(Math.random() * 1e6)}`;
+    const prdsDir = path.join(projectCwd, 'session-manager-operations', 'scheduler', 'prds');
+    fs.mkdirSync(prdsDir, { recursive: true });
+    // parsePrd rejects any PRD over 1MB with a plain Error (no .code) — this
+    // is the "found but unparseable" case, distinct from ENOENT, and must
+    // stay a real failure.
+    const oversized = '---\ntitle: too big\n---\n\n' + 'x'.repeat(1024 * 1024 + 1);
+    fs.writeFileSync(path.join(prdsDir, `${slug}.md`), oversized, 'utf8');
+
+    const job = { slug, cwd: projectCwd };
+    const result = await executeJob(job, runDir, projectCwd, () => {});
+
+    expect(result.exitCode).toBe(-1);
+    expect(result.skipped).toBeUndefined();
+  } finally {
+    fs.rmSync(projectCwd, { recursive: true, force: true });
+    fs.rmSync(runDir, { recursive: true, force: true });
+  }
+});

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

@@ -6,6 +6,14 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
+// HOME stubbed BEFORE requiring scheduler.cjs (PRD 812 fix): the last
+// describe block below calls scheduler.reconcile(), which internally calls
+// ensureDirs() → fs.mkdirSync on PRDS_DIR/RUNS_DIR — paths baked from
+// os.homedir() at require time. Without this stub that mkdirSync lands in
+// the real `~/.claude/session-manager/scheduled-plans/` tree.
+const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-832-home-'));
+process.env.HOME = tmpHome;
+
 const prdParser = require('../scheduler/prdParser.cjs');
 const { pickForProject } = require('../lib/schedulerBatch.cjs');
 

package/src/main/index.cjs

@@ -28,6 +28,7 @@ const voiceWizard = require('./voiceWizard.cjs');
 const scheduler = require('./scheduler.cjs');
 const { createAdminHttp } = require('./lib/localAdminHttp.cjs');
 const prdCreate = require('./lib/prdCreate.cjs');
+const { appendAuditEvent } = require('./lib/auditLog.cjs');
 const chatRunner = require('./chatRunner.cjs');
 const promptSessionEvents = require('./promptSessionEvents.cjs');
 const agentLibrary = require('./agentLibrary.cjs');
@@ -799,6 +800,12 @@ ipcMain.handle('promptSessionTranscript:read', validated(schemas.promptSessionTr
   const turns = await promptSessionTranscript.readTurns(cwd, epicId, { limit });
   return { turns };
 }));
+// Renderer Epic lifecycle trace (PRD 940) — append-only, no read/list IPC.
+// Kind allowlist enforced by schemas.auditLogAppend, not here.
+ipcMain.handle('auditLog:append', validated(schemas.auditLogAppend, async ({ kind, cwd, epicId, source }) => {
+  appendAuditEvent(kind, { cwd, epicId, source });
+  return { ok: true };
+}));
 agentMemory.registerAgentMemoryHandlers();
 git.register(ipcMain);
 filesIpc.registerFilesHandlers();

package/src/main/ipcSchemas.cjs

@@ -493,6 +493,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 +908,7 @@ module.exports = {
     projectBriefUpdate,
     promptSessionTranscriptAppend,
     promptSessionTranscriptRead,
+    auditLogAppend,
     agentMemoryList,
     agentMemoryGet,
     agentMemorySet,

package/src/main/lib/epicMint.cjs

@@ -182,9 +182,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 +227,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 +261,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 +277,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 = {

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>;

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 }),