claude-code-session-manager 0.89.0 → 0.91.0

package/src/main/__tests__/transcripts-worktree-epic-path.test.cjs

@@ -0,0 +1,154 @@
+/**
+ * transcripts-worktree-epic-path.test.cjs — transcriptPath()/subscribe() resolve
+ * an Epic's transcript through epicTranscriptPath (worktree encoding), while a
+ * non-Epic tab keeps the plain project encoding. Includes a parity check of the
+ * renderer's transcriptExists() (EpicTerminalPane's resume-vs-create decision)
+ * against the REAL transcriptPath instead of a constant mock.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/transcripts-worktree-epic-path.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeAll, afterAll, beforeEach, afterEach, vi } from 'vitest';
+import { transcriptExists } from '../../renderer/lib/transcriptExists';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+let tmpHome;
+let originalHome;
+let tr;
+let resolver;
+let encodeCwd;
+let proj;
+const SID = 'b8a5d6f4-0092-4db0-a687-009241f2a8b2';
+const WT = '/tmp/sm-wt-test-epic-worktree-dir';
+
+beforeAll(() => {
+  originalHome = process.env.HOME;
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-transcripts-wt-home-'));
+  process.env.HOME = tmpHome;
+  tr = require('../transcripts.cjs');
+  resolver = require('../lib/epicTranscriptPath.cjs');
+  ({ encodeCwd } = require('../lib/encodeCwd.cjs'));
+});
+
+afterAll(() => {
+  process.env.HOME = originalHome;
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+
+beforeEach(() => {
+  resolver.__resetCacheForTests();
+  proj = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-transcripts-wt-proj-'));
+});
+
+afterEach(() => {
+  fs.rmSync(proj, { recursive: true, force: true });
+  fs.rmSync(path.join(tmpHome, '.claude'), { recursive: true, force: true });
+  vi.unstubAllGlobals();
+});
+
+const projectsDir = () => path.join(tmpHome, '.claude', 'projects');
+const plain = (cwd, id = SID) => path.join(projectsDir(), encodeCwd(cwd), `${id}.jsonl`);
+
+function writeIndex(sessionId = SID) {
+  const dir = path.join(proj, 'session-manager-operations', 'prompt-sessions');
+  fs.mkdirSync(dir, { recursive: true });
+  const s = { id: 'epic-1', cwd: proj, claudeSessionId: sessionId, status: 'active', worktree: { dir: WT, branch: 'sm-epic/epic-1', baseCwd: proj, status: 'active' } };
+  fs.writeFileSync(path.join(dir, 'active-index.json'), JSON.stringify({ sessions: { 'epic-1': s }, events: {} }));
+}
+
+function writeTranscript(p, body = '{"type":"user"}\n') {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, body);
+}
+
+test('worktree-present: transcript only under the worktree encoding resolves there', () => {
+  writeIndex();
+  fs.mkdirSync(WT, { recursive: true });
+  try {
+    writeTranscript(plain(WT));
+    expect(tr.transcriptPath(proj, SID)).toBe(plain(WT));
+  } finally {
+    fs.rmSync(WT, { recursive: true, force: true });
+  }
+});
+
+test('worktree-swept: worktree dir gone from disk, transcript still found', () => {
+  writeIndex();
+  expect(fs.existsSync(WT)).toBe(false);
+  writeTranscript(plain(WT));
+  expect(tr.transcriptPath(proj, SID)).toBe(plain(WT));
+});
+
+test('non-Epic tab resolves to exactly the pre-change path, even when an Epic exists', () => {
+  writeIndex();
+  writeTranscript(plain(WT));
+  const rawTab = 'raw-tab-id-123';
+  expect(tr.transcriptPath(proj, rawTab)).toBe(path.join(os.homedir(), '.claude', 'projects', encodeCwd(proj), `${rawTab}.jsonl`));
+  // no index at all
+  const other = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-transcripts-wt-other-'));
+  try {
+    expect(tr.transcriptPath(other, SID)).toBe(plain(other));
+    expect(path.isAbsolute(tr.transcriptPath(other, SID))).toBe(true);
+  } finally {
+    fs.rmSync(other, { recursive: true, force: true });
+  }
+});
+
+test('zero-byte transcript counts as existing and does not break usageFor', async () => {
+  writeIndex();
+  writeTranscript(plain(WT), '');
+  expect(tr.transcriptPath(proj, SID)).toBe(plain(WT));
+  const out = await tr.usageFor(proj, [SID]);
+  expect(out).toHaveProperty(SID);
+});
+
+test('subscribe does NOT mkdir when a transcript exists elsewhere (worktree encoding)', async () => {
+  writeIndex();
+  writeTranscript(plain(WT));
+  const before = fs.readdirSync(projectsDir()).sort();
+  const res = await tr.subscribe({ tabId: 'tab-wt', cwd: proj, sessionUuid: SID });
+  try {
+    expect(res.ok).toBe(true);
+    expect(res.path).toBe(plain(WT));
+    expect(fs.readdirSync(projectsDir()).sort()).toEqual(before);
+    expect(fs.existsSync(path.dirname(plain(proj)))).toBe(false);
+  } finally {
+    tr.closeTab('tab-wt');
+  }
+});
+
+test('subscribe of a brand-new Epic watches the spawn-cwd path and creates its dir', async () => {
+  writeIndex();
+  const res = await tr.subscribe({ tabId: 'tab-new', cwd: proj, sessionUuid: SID });
+  try {
+    expect(res.ok).toBe(true);
+    // no transcript anywhere → resolver's first candidate (spawn cwd), whose dir the CLI will write
+    expect(fs.existsSync(path.dirname(res.path))).toBe(true);
+    expect(fs.existsSync(res.path)).toBe(false);
+  } finally {
+    tr.closeTab('tab-new');
+  }
+});
+
+test('parity: renderer transcriptExists (Terminal resume decision) sees a worktree-only transcript', async () => {
+  writeIndex();
+  vi.stubGlobal('window', {
+    api: {
+      transcripts: { pathFor: async (c, s) => tr.transcriptPath(c, s) },
+      config: { exists: async (p) => fs.existsSync(p) },
+    },
+  });
+  expect(await transcriptExists(proj, SID)).toBe(false);
+  writeTranscript(plain(WT));
+  expect(await transcriptExists(proj, SID)).toBe(true);
+  // zero-byte still "exists"
+  writeTranscript(plain(WT), '');
+  expect(await transcriptExists(proj, SID)).toBe(true);
+  // raw tab never resolves into the Epic's worktree encoding
+  expect(await transcriptExists(proj, 'raw-tab')).toBe(false);
+});

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

@@ -89,7 +89,9 @@ afterEach(() => {
   vi.unstubAllGlobals();
   vi.restoreAllMocks();
   purgeRequireCache();
-  fs.rmSync(tmpHome, { recursive: true, force: true });
+  // maxRetries: a fire-and-forget cache write inside usage.cjs can land in .claude/ mid-rm
+  // (ENOTEMPTY) when the machine is loaded; this is cleanup robustness, not a test retry.
+  fs.rmSync(tmpHome, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
 });
 
 test('two concurrent fetchUsage() calls produce exactly one HTTP fetch', async () => {

package/src/main/bilkoHost.cjs

@@ -220,13 +220,12 @@ async function removeDocument({ cwd, id }) {
 
 async function resolveDocumentHtml(cwd, doc) {
   if (doc.source.kind === 'project-page-lens') {
-    // Only `home` is generated now (one home.html); the other lens names
-    // are legacy and resolve to their old output/<lens>.html if one exists.
-    const result = await config.readText(
-      doc.source.lens === 'home'
-        ? homePagePath(cwd)
-        : opsPath(cwd, 'project-pages', 'output', `${doc.source.lens}.html`),
-    );
+    // Only `home` is generated now (one home.html); other lens names are
+    // retired and have no output anywhere — fail loudly rather than fall back.
+    if (doc.source.lens !== 'home') {
+      throw new Error(`document "${doc.title}" points at the retired "${doc.source.lens}" Project Page lens; only the single home.html page is generated now`);
+    }
+    const result = await config.readText(homePagePath(cwd));
     if (!result.exists) {
       throw new Error(`document "${doc.title}" points at the ${doc.source.lens} Project Page, but it hasn't been generated yet`);
     }

package/src/main/build-info.json

@@ -1,8 +1,8 @@
 {
-  "version": "0.89.0",
-  "gitSha": "5ec3affd400f9a33189925d332d9c253fee1120c",
-  "gitShortSha": "5ec3aff",
+  "version": "0.91.0",
+  "gitSha": "0029caa246d6296f7f8e83a502f5351c670b269c",
+  "gitShortSha": "0029caa",
   "gitBranch": "HEAD",
-  "builtAt": "2026-09-19T22:24:34.621Z",
+  "builtAt": "2026-09-20T19:42:50.657Z",
   "dirty": false
 }

package/src/main/chatRunner.cjs

@@ -53,7 +53,14 @@ const { classifyPromptTicket } = require('./lib/classifyPromptTicket.cjs');
 const sessionSlots = require('./lib/sessionSlots.cjs');
 const opsErrorLog = require('./lib/opsErrorLog.cjs');
 const agentModelResolve = require('./lib/agentModelResolve.cjs');
-const { resolveEpicSpawnCwd } = require('./lib/epicSpawnCwd.cjs');
+const { planEpicSpawn } = require('./lib/epicSpawnPlan.cjs');
+const logs = require('./logs.cjs');
+
+// The only two CLI errors that mean "wrong session flag" (verified against the
+// real CLI). "in use" → the transcript exists, so resume; "no conversation" →
+// nothing to resume, so create. Never widen this into a general retry.
+const SESSION_IN_USE_RE = /Session ID .* is already in use/i;
+const NO_CONVERSATION_RE = /No conversation found with session ID/i;
 
 // ─── Stop-signal protocol ──────────────────────────────────────────────────
 // Single source of truth for the sentinel and parser. The renderer (PRD 320)
@@ -540,21 +547,43 @@ function executeRun({ tabId, sessionId, prompt, cwd, resume, silent, onSilentRes
     // must never be left unpinned (CLAUDE.md model-pinning rule).
     const model = agentModelResolve.resolveEpicModel({ cwd, claudeSessionId: sessionId });
 
-    // Build argv as an array — no shell: true, no string interpolation
-    const args = [
-      '-p', fullPrompt,
-      '--model', model,
-      '--dangerously-skip-permissions',
-      '--output-format', 'stream-json',
-      '--verbose',
-    ];
-    if (resume) {
-      // --resume carries the session context; no --session-id needed
-      args.push('--resume', sessionId);
-    } else {
-      args.push('--session-id', sessionId);
+    // Main is authoritative about --resume vs --session-id AND the spawn cwd, and it decides
+    // them TOGETHER (epicSpawnPlan.cjs): a transcript under an encoding the spawn cwd cannot see
+    // must never yield a claimed flag. Unreachable / closed Epics are refused before any spawn.
+    const plan = planEpicSpawn({ cwd, claudeSessionId: sessionId, fallbackResume: !!resume });
+    if (!plan.ok) {
+      emitTerminal('chat:run:error', { tabId, sessionId, code: plan.code, message: plan.message });
+      settle();
+      return;
+    }
+    const useResume = plan.useResume;
+    if (useResume !== !!resume) {
+      try {
+        logs.writeLine({
+          scope: 'chatRunner',
+          level: 'warn',
+          message: `session flag mismatch: renderer resume=${!!resume}, main resume=${useResume}; transcript=${plan.transcriptPath ?? 'none'}`,
+          meta: { tabId, sessionId, rendererResume: !!resume, mainResume: useResume, transcriptPath: plan.transcriptPath ?? null },
+        });
+      } catch { /* logging must never fail a turn */ }
     }
 
+    // Build argv as an array — no shell: true, no string interpolation. Also
+    // used for the flag-swap retry so both attempts share one construction path.
+    const buildArgs = (resumeFlag) => {
+      const a = [
+        '-p', fullPrompt,
+        '--model', model,
+        '--dangerously-skip-permissions',
+        '--output-format', 'stream-json',
+        '--verbose',
+      ];
+      // --resume carries the session context; no --session-id needed
+      if (resumeFlag) a.push('--resume', sessionId);
+      else a.push('--session-id', sessionId);
+      return a;
+    };
+
     if (!silent) broadcast('chat:run:started', { tabId, sessionId });
 
     // sessionId IS the Epic's claudeSessionId for an Epic-backed tab (see
@@ -564,36 +593,14 @@ function executeRun({ tabId, sessionId, prompt, cwd, resume, silent, onSilentRes
     // below keeps using it exactly as before — only this ACTUAL spawn cwd
     // option does. See epicSpawnCwd.cjs's header comment (the ops-root
     // hazard) and jobWorktree.cjs's own (execCwd vs job.cwd) for why.
-    const execCwd = resolveEpicSpawnCwd({ cwd, claudeSessionId: sessionId });
+    const execCwd = plan.execCwd;
 
-    // Spawn with stdin closed (mirrors scheduler's 'ignore' — prevents the
-    // "claude -p stdin must be closed" gotcha from kg.cjs). stdout is piped for
-    // real-time NDJSON streaming; stderr piped for error-message capture.
-    let child;
-    try {
-      const target = claudeSpawnTarget('chat', sessionId, claudeBin);
-      child = spawn(target.command, args, {
-        ...(target.argv0 ? { argv0: target.argv0 } : {}),
-        cwd: execCwd,
-        env: childEnv,
-        stdio: ['ignore', 'pipe', 'pipe'],
-        detached: true, // own process group so killTree can SIGTERM descendants
-      });
-    } catch (err) {
-      emitTerminal('chat:run:error', {
-        tabId,
-        sessionId,
-        message: `spawn failed: ${err?.message ?? String(err)}`,
-      });
-      settle();
-      return;
-    }
-
-    // One-shot kill helper — idempotent via the `killed` flag
     let killed = false;
+    let child = null;
     const doKill = (sig) => {
       if (killed) return;
       killed = true;
+      if (!child) return;
       // Negative pid targets the process group (requires detached: true)
       try { process.kill(-child.pid, sig); }
       catch { try { child.kill(sig); } catch { /* already dead */ } }
@@ -647,10 +654,40 @@ function executeRun({ tabId, sessionId, prompt, cwd, resume, silent, onSilentRes
     }, KILL_CEILING_MS);
     if (killTimer.unref) killTimer.unref();
 
+    // One spawn of the CLI. Per-attempt state (buffers, child) lives in here;
+    // everything turn-level (timers, latch, lane) is in the enclosing scope.
+    const startAttempt = (resumeFlag, attemptNo) => {
+    // Spawn with stdin closed (mirrors scheduler's 'ignore' — prevents the
+    // "claude -p stdin must be closed" gotcha from kg.cjs). stdout is piped for
+    // real-time NDJSON streaming; stderr piped for error-message capture.
+    let thisChild;
+    try {
+      const target = claudeSpawnTarget('chat', sessionId, claudeBin);
+      thisChild = spawn(target.command, buildArgs(resumeFlag), {
+        ...(target.argv0 ? { argv0: target.argv0 } : {}),
+        cwd: execCwd,
+        env: childEnv,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        detached: true, // own process group so killTree can SIGTERM descendants
+      });
+    } catch (err) {
+      clearTimeout(killTimer);
+      clearTimeout(warnTimer);
+      emitTerminal('chat:run:error', {
+        tabId,
+        sessionId,
+        message: `spawn failed: ${err?.message ?? String(err)}`,
+      });
+      settle();
+      return;
+    }
+    child = thisChild;
+
     // ─── Stream parsing ────────────────────────────────────────────────────
     // stdout is newline-delimited JSON (stream-json format). We buffer partial
     // lines across TCP/pipe chunks. O(output-size) in memory per run.
 
+    // Per-attempt state — a retry starts from empty buffers.
     let lineBuffer = '';
     let finalAssistantText = '';
     let stderrBuffer = '';
@@ -738,7 +775,7 @@ function executeRun({ tabId, sessionId, prompt, cwd, resume, silent, onSilentRes
       }
     };
 
-    child.stdout.on('data', (chunk) => {
+    thisChild.stdout.on('data', (chunk) => {
       lineBuffer += chunk.toString('utf8');
       let nl;
       while ((nl = lineBuffer.indexOf('\n')) !== -1) {
@@ -747,11 +784,11 @@ function executeRun({ tabId, sessionId, prompt, cwd, resume, silent, onSilentRes
       }
     });
 
-    child.stderr.on('data', (chunk) => {
+    thisChild.stderr.on('data', (chunk) => {
       stderrBuffer += chunk.toString('utf8');
     });
 
-    child.on('error', (err) => {
+    thisChild.on('error', (err) => {
       clearTimeout(killTimer);
       clearTimeout(warnTimer);
       emitTerminal('chat:run:error', {
@@ -768,12 +805,35 @@ function executeRun({ tabId, sessionId, prompt, cwd, resume, silent, onSilentRes
     // line) reaches the 'data' handler above, which raced this fallback into
     // firing first and dropping the real chat:run:complete behind the
     // terminalSent latch.
-    child.on('close', (code, signal) => {
-      clearTimeout(killTimer);
-      clearTimeout(warnTimer);
+    thisChild.on('close', (code, signal) => {
       // Flush any partial line that didn't end with \n
       if (lineBuffer.trim()) processLine(lineBuffer.trim());
 
+      // Flag-swap retry: the CLI rejected the session flag before doing any
+      // work. Retry exactly once with the other flag; the timers, lane and
+      // terminal latch stay at executeRun level, so this is still one turn.
+      if (!terminalSent && !killed && code !== 0 && attemptNo === 1
+          && finalAssistantText === '' && recentToolUses.length === 0
+          && !/rate.?limit/i.test(stderrBuffer)) {
+        const swapTo = resumeFlag
+          ? (NO_CONVERSATION_RE.test(stderrBuffer) ? false : null)
+          : (SESSION_IN_USE_RE.test(stderrBuffer) ? true : null);
+        if (swapTo !== null) {
+          if (!silent) {
+            broadcast('chat:run:notice', {
+              tabId,
+              sessionId,
+              message: `Session flag mismatch (${resumeFlag ? '--resume' : '--session-id'} rejected); retrying once with ${swapTo ? '--resume' : '--session-id'}.`,
+            });
+          }
+          startAttempt(swapTo, 2);
+          return;
+        }
+      }
+
+      clearTimeout(killTimer);
+      clearTimeout(warnTimer);
+
       // Emit a fallback terminal event for any run that ended without one — a
       // cancel/SIGTERM (killed=true), a crash before a result, or a silent
       // exit. `emitTerminal` no-ops if the run already sent complete/needs-
@@ -799,6 +859,9 @@ function executeRun({ tabId, sessionId, prompt, cwd, resume, silent, onSilentRes
       }
       settle();
     });
+    };
+
+    startAttempt(useResume, 1);
   });
 }
 

package/src/main/health.cjs

@@ -25,6 +25,7 @@ const { auditLogPath, readTail } = require('./lib/auditLog.cjs');
 const { resolveBuildIdentity } = require('./lib/buildIdentity.cjs');
 const { DEFAULT_RUNS_DIR, computeReport, isRetentionEnabled, liveKeysFromJobs } = require('./lib/runLogRetention.cjs');
 const { allProjectCwds } = require('./lib/activeSessions.cjs');
+const { scanEpicTranscripts } = require('./lib/epicTranscriptDiagnostic.cjs');
 
 const MAX_LOG_AGE_MS = 5 * 60_000; // 5 min — warn if no logs this old
 const PROJECT_ROOT = path.resolve(__dirname, '../..');
@@ -716,7 +717,10 @@ function evaluateBlockingParkHealth(jobs, now, thresholdMs = REVERIFY_INTERVAL_M
   };
 }
 
-async function check() {
+// opts.skipTypecheck: skip the whole-repo `tsc` shell-out (~15s idle, unbounded under CPU load).
+// For callers that assert on one other component; the typescript component is then
+// reported { ok: true, skipped: true } so it can never read as a real pass.
+async function check(opts = {}) {
   const start = Date.now();
   const status = {
     ok: true,
@@ -736,8 +740,8 @@ async function check() {
   }
 
   // 1.5. Check TypeScript compilation (no errors).
-  const typesOk = runCheck('npm run typecheck 2>&1 | grep -q "error" && exit 1 || exit 0');
-  status.components.typescript = { ok: typesOk };
+  const typesOk = opts.skipTypecheck ? true : runCheck('npm run typecheck 2>&1 | grep -q "error" && exit 1 || exit 0');
+  status.components.typescript = opts.skipTypecheck ? { ok: true, skipped: true } : { ok: typesOk };
   if (!typesOk) {
     status.issues.push('TypeScript compilation has errors');
     status.ok = false;
@@ -1146,6 +1150,19 @@ async function check() {
     status.issues.push(`Epic index health check failed: ${e.message}`);
   }
 
+  // 6.66. Epic transcript location (NON-fatal warning): a mislocated/duplicated
+  // transcript is read correctly by epicTranscriptPath, so it never reddens the
+  // rollup (not in criticalComponents). See scripts/check-epic-transcripts.cjs.
+  try {
+    const findings = scanEpicTranscripts({ cwds: allProjectCwds() });
+    status.components.epic_transcripts = { ok: true, findings: findings.length, duplicated: findings.filter((f) => f.classification === 'duplicated').length };
+    if (findings.length > 0) {
+      status.issues.push(`Warning: ${findings.length} Epic transcript(s) mislocated/duplicated — run: node scripts/check-epic-transcripts.cjs`);
+    }
+  } catch (e) {
+    status.components.epic_transcripts = { ok: true, error: e.message };
+  }
+
   // 6.7. Build freshness (informational): running heartbeat vs installed
   // build-info vs repo HEAD.
   try {

package/src/main/index.cjs

@@ -513,7 +513,7 @@ ipcMain.handle('app:launch-mode', () => ({
 // `claude mcp list`. Read-only, single in-flight call — no polling.
 ipcMain.handle('mcp:status', () => probeMcpStatus());
 
-// Project Home's "Agent tools" block (PhAgentTools): the same catalog data
+// The Dashboard's "Agent tools" section (HomeAgentTools): the same catalog data
 // GET /admin/mcp/catalog serves to external callers, read in-process here so
 // the renderer never makes a direct HTTP call. Static data, no cwd needed.
 ipcMain.handle('mcp:catalog', () => ({ ok: true, tools: MCP_TOOL_CATALOG, recipes: MCP_RECIPES }));

package/src/main/ipcSchemas.cjs

@@ -351,6 +351,9 @@ const schedulerCreatePrd = z.object({
   // createPrd() requires it in that situation for an interactive caller and
   // defaults to 'append' (logged as a default) for a non-interactive one.
   disposition: PrdDispositionSchema.optional(),
+  // Artifact-only PRD declaration — cross-field rules enforced in prdCreate.cjs.
+  deliverable: z.literal('artifact').optional(),
+  artifactPaths: z.array(z.string().min(1).max(1024).regex(NO_NEWLINE_RE, 'must not contain newlines')).max(50).optional(),
   // An EXISTING Epic's promptSessionId (PRD 748) — NOT a PromptTicket.id.
   // ensureEpic() (epicMint.cjs) joins the Epic whose active-index.json
   // sessions key literally equals this value; the renderer only ever sends

package/src/main/lib/__tests__/epicSpawnCwd.test.cjs

@@ -191,3 +191,37 @@ test('a real, existing directory IS returned — the check gates on disk state,
     fs.rmSync(realDir, { recursive: true, force: true });
   }
 });
+
+// ─── spawn-side: a vanished worktree is restored at the SAME path, never swapped for cwd ───
+
+test('restore:true re-attaches the worktree and returns the recorded dir (transcript encoding unchanged)', () => {
+  const calls = [];
+  const result = resolveEpicSpawnCwd({
+    cwd: '/projects/foo',
+    claudeSessionId: 'sess-1',
+    deps: {
+      readActiveIndex: stubReadActiveIndex(WORKTREE_SESSIONS),
+      statSync: statGone,
+      restore: true,
+      restoreWorktree: (a) => { calls.push(a); return true; },
+    },
+  });
+  expect(result).toBe('/tmp/session-manager-epic-worktrees/deadbeef/epic-1');
+  expect(calls).toEqual([{ dir: '/tmp/session-manager-epic-worktrees/deadbeef/epic-1', branch: 'sm-epic/epic-1', baseCwd: '/projects/foo' }]);
+});
+
+test('restore:true with a failed restore still returns the recorded dir — never the project cwd', () => {
+  const result = resolveEpicSpawnCwd({
+    cwd: '/projects/foo',
+    claudeSessionId: 'sess-1',
+    deps: { readActiveIndex: stubReadActiveIndex(WORKTREE_SESSIONS), statSync: statGone, restore: true, restoreWorktree: () => false },
+  });
+  expect(result).toBe('/tmp/session-manager-epic-worktrees/deadbeef/epic-1');
+});
+
+test('restoreEpicWorktree refuses dirs outside an epic-worktrees segment and non sm-epic branches', () => {
+  const { restoreEpicWorktree } = require('../epicSpawnCwd.cjs');
+  expect(restoreEpicWorktree({ dir: '/etc/evil', branch: 'sm-epic/x', baseCwd: '/projects/foo' })).toBe(false);
+  expect(restoreEpicWorktree({ dir: '/tmp/session-manager-epic-worktrees/a/b', branch: 'main; rm -rf', baseCwd: '/projects/foo' })).toBe(false);
+  expect(restoreEpicWorktree({ dir: 'relative/session-manager-epic-worktrees/a', branch: 'sm-epic/x', baseCwd: '/projects/foo' })).toBe(false);
+});

package/src/main/lib/__tests__/epicSpawnPlan.test.cjs

@@ -0,0 +1,117 @@
+/**
+ * epicSpawnPlan.test.cjs — PRD 1319: spawn cwd + --resume flag are decided together; a session
+ * whose transcript is stranded under a dead worktree encoding is refused BEFORE any CLI spawn
+ * with an actionable message, later requests are refused cheaply, closed Epics are refused.
+ *
+ * Run: timeout 120 npx vitest run src/main/lib/__tests__/epicSpawnPlan.test.cjs
+ */
+'use strict';
+
+import { test, expect, beforeEach, afterEach } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { EventEmitter } = require('node:events');
+const { encodeCwd } = require('../encodeCwd.cjs');
+const { planEpicSpawn, __resetForTests } = require('../epicSpawnPlan.cjs');
+const { __resetCacheForTests } = require('../epicTranscriptPath.cjs');
+
+const SID = '00ff31cb-56b6-421c-829c-012ef95b15e2';
+const PROJECT = '/projects/starry-night-ships';
+const DEAD = '/tmp/session-manager-epic-worktrees/abc123/blender-epic-442d711d';
+
+let home;
+beforeEach(() => {
+  __resetForTests();
+  __resetCacheForTests();
+  home = fs.mkdtempSync(path.join(os.tmpdir(), 'plan-home-'));
+});
+afterEach(() => fs.rmSync(home, { recursive: true, force: true }));
+
+function transcriptUnder(dir) {
+  const d = path.join(home, '.claude', 'projects', encodeCwd(dir));
+  fs.mkdirSync(d, { recursive: true });
+  const f = path.join(d, `${SID}.jsonl`);
+  fs.writeFileSync(f, '{"type":"user"}\n');
+  return f;
+}
+const epic = (extra = {}) => ({ e1: { id: 'e1', claudeSessionId: SID, status: 'active', worktree: { dir: DEAD, branch: 'sm-epic/e1', baseCwd: PROJECT, status: 'active' }, ...extra } });
+
+test('transcript under a dead worktree encoding + restore failure => refused, names the worktree, no raw CLI text', () => {
+  transcriptUnder(DEAD);
+  const plan = planEpicSpawn({ cwd: PROJECT, claudeSessionId: SID, deps: { homeDir: home, readActiveIndex: () => ({ sessions: epic() }), restoreWorktree: () => false } });
+  expect(plan.ok).toBe(false);
+  expect(plan.code).toBe('session_unreachable');
+  expect(plan.message).toContain(DEAD);
+  expect(plan.message).not.toMatch(/already in use/i);
+});
+
+test('circuit breaker: 2nd..Nth request refused without re-running restore', () => {
+  transcriptUnder(DEAD);
+  let restores = 0;
+  const deps = { homeDir: home, readActiveIndex: () => ({ sessions: epic() }), restoreWorktree: () => { restores++; return false; } };
+  const first = planEpicSpawn({ cwd: PROJECT, claudeSessionId: SID, deps });
+  for (let i = 0; i < 4; i++) expect(planEpicSpawn({ cwd: PROJECT, claudeSessionId: SID, deps })).toEqual(first);
+  expect(restores).toBe(1);
+});
+
+test('worktree re-attached at the same path => ok, resume, spawn cwd is the worktree', () => {
+  transcriptUnder(DEAD);
+  const live = new Set();
+  const statSync = (p) => (live.has(p) ? { isDirectory: () => true } : fs.statSync(p));
+  const plan = planEpicSpawn({
+    cwd: PROJECT, claudeSessionId: SID,
+    deps: { homeDir: home, readActiveIndex: () => ({ sessions: epic() }), statSync, restoreWorktree: ({ dir }) => { live.add(dir); return true; } },
+  });
+  expect(plan.ok).toBe(true);
+  expect(plan.useResume).toBe(true);
+  expect(plan.execCwd).toBe(DEAD);
+});
+
+test('transcript under the project encoding, no worktree => ok, resume from project cwd', () => {
+  transcriptUnder(PROJECT);
+  const plan = planEpicSpawn({ cwd: PROJECT, claudeSessionId: SID, deps: { homeDir: home, readActiveIndex: () => ({ sessions: epic({ worktree: undefined }) }), statSync: (p) => (p === PROJECT ? { isDirectory: () => true } : fs.statSync(p)) } });
+  expect(plan).toMatchObject({ ok: true, useResume: true, execCwd: PROJECT });
+});
+
+test('closed (completed) Epic is refused with its own message', () => {
+  const plan = planEpicSpawn({ cwd: PROJECT, claudeSessionId: SID, deps: { homeDir: home, readActiveIndex: () => ({ sessions: epic({ status: 'completed' }) }) } });
+  expect(plan).toMatchObject({ ok: false, code: 'epic_closed' });
+  expect(plan.message).toMatch(/closed/i);
+});
+
+test('chatRunner: dead-encoding transcript => zero CLI spawns, exactly one clear error event', async () => {
+  const project = fs.mkdtempSync(path.join(os.tmpdir(), 'plan-proj-'));
+  const prevHome = process.env.HOME;
+  process.env.HOME = home;
+  try {
+    const idxDir = path.join(project, 'session-manager-operations', 'prompt-sessions');
+    fs.mkdirSync(idxDir, { recursive: true });
+    fs.writeFileSync(path.join(idxDir, 'active-index.json'), JSON.stringify({ sessions: epic() }));
+    transcriptUnder(DEAD);
+    const cp = require('node:child_process');
+    const realSpawn = cp.spawn;
+    let spawns = 0;
+    cp.spawn = () => { spawns++; const c = new EventEmitter(); c.stdout = new EventEmitter(); c.stderr = new EventEmitter(); c.pid = 1; c.kill = () => {}; return c; };
+    const chatRunner = require('../../chatRunner.cjs');
+    chatRunner.__resetQueueForTests();
+    const sent = [];
+    chatRunner.attachWindow({ isDestroyed: () => false, webContents: { isDestroyed: () => false, send: (channel, payload) => sent.push({ channel, payload }) } });
+    try {
+      for (let i = 0; i < 3; i++) chatRunner.run({ tabId: `t${i}`, sessionId: SID, prompt: 'hi', cwd: project, resume: true });
+      await new Promise((r) => setTimeout(r, 100));
+    } finally { cp.spawn = realSpawn; }
+    const errs = sent.filter((e) => e.channel === 'chat:run:error');
+    expect(spawns).toBe(0);
+    expect(errs.length).toBe(3);
+    for (const e of errs) expect(e.payload.message).toContain(DEAD);
+    // Single-writer law: the rescued session's ops write (error log) lands under the PROJECT root.
+    const logsDir = path.join(project, 'session-manager-operations', 'logs');
+    expect(fs.existsSync(logsDir)).toBe(true);
+    expect(fs.readdirSync(logsDir).some((n) => n.startsWith('errors-'))).toBe(true);
+    expect(fs.existsSync(path.join(DEAD, 'session-manager-operations'))).toBe(false);
+  } finally {
+    process.env.HOME = prevHome;
+    fs.rmSync(project, { recursive: true, force: true });
+  }
+});