claude-code-session-manager 0.89.0 → 0.90.0

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/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 });
+  }
+});

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

@@ -0,0 +1,163 @@
+/**
+ * epicTranscriptPath.test.cjs — resolver for where an Epic session's JSONL
+ * transcript actually lives (worktree encoding vs project encoding).
+ *
+ * Run: timeout 120 npx vitest run src/main/lib/__tests__/epicTranscriptPath.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 { resolveEpicTranscriptPath, __resetCacheForTests } = require('../epicTranscriptPath.cjs');
+const { encodeCwd } = require('../encodeCwd.cjs');
+const { readActiveIndex } = require('../epicMint.cjs');
+
+const SID = 'sess-1';
+let root, home, cwd, wtDir;
+
+const projFile = (dir) => path.join(home, '.claude', 'projects', encodeCwd(dir), `${SID}.jsonl`);
+function put(p, body = '{"a":1}\n', mtimeSec) {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, body);
+  if (mtimeSec) fs.utimesSync(p, mtimeSec, mtimeSec);
+}
+const promptDir = () => path.join(cwd, 'session-manager-operations', 'prompt-sessions');
+function writeIndex(sessions) {
+  fs.mkdirSync(promptDir(), { recursive: true });
+  fs.writeFileSync(path.join(promptDir(), 'active-index.json'), JSON.stringify({ sessions, events: {} }));
+}
+const epic = (extra = {}) => ({ id: 'epic-1', claudeSessionId: SID, worktree: { dir: wtDir, branch: 'b', baseCwd: cwd, status: 'active' }, ...extra });
+const resolve = (deps = {}) => resolveEpicTranscriptPath({ cwd, claudeSessionId: SID, deps: { homeDir: home, ...deps } });
+
+beforeEach(() => {
+  __resetCacheForTests();
+  root = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-etp-'));
+  home = path.join(root, 'home');
+  cwd = path.join(root, 'project');
+  wtDir = path.join(root, 'wt', 'epic-1');
+  fs.mkdirSync(cwd, { recursive: true });
+});
+afterEach(() => fs.rmSync(root, { recursive: true, force: true }));
+
+test('worktree transcript is found when the worktree dir exists', () => {
+  fs.mkdirSync(wtDir, { recursive: true });
+  writeIndex({ e: epic() });
+  put(projFile(wtDir));
+  const r = resolve();
+  expect(r.path).toBe(projFile(wtDir));
+  expect(r.existsAnywhere).toBe(true);
+  expect(r.candidates).toEqual([projFile(wtDir), projFile(cwd)]);
+});
+
+test('worktree swept from disk but transcript survives — still returned', () => {
+  writeIndex({ e: epic() });
+  put(projFile(wtDir));
+  const r = resolve();
+  expect(r.path).toBe(projFile(wtDir));
+  expect(r.candidates).toContain(projFile(wtDir));
+});
+
+test('project-encoding-only transcript', () => {
+  fs.mkdirSync(wtDir, { recursive: true });
+  writeIndex({ e: epic() });
+  put(projFile(cwd));
+  const r = resolve();
+  expect(r.path).toBe(projFile(cwd));
+  expect(r.existingPaths).toEqual([projFile(cwd)]);
+});
+
+test('nothing anywhere: path is the spawn-cwd candidate, existsAnywhere false', () => {
+  fs.mkdirSync(wtDir, { recursive: true });
+  writeIndex({ e: epic() });
+  const r = resolve();
+  expect(r.path).toBe(projFile(wtDir));
+  expect(r.existsAnywhere).toBe(false);
+  expect(r.existingPaths).toEqual([]);
+});
+
+test('non-Epic tab returns exactly the project path with a single candidate', () => {
+  writeIndex({ e: epic({ claudeSessionId: 'other' }) });
+  put(projFile(cwd));
+  const r = resolve();
+  expect(r.candidates).toEqual([projFile(cwd)]);
+  expect(r.path).toBe(projFile(cwd));
+});
+
+test('dir exists but holds only a tool-results sidecar — does not win', () => {
+  fs.mkdirSync(wtDir, { recursive: true });
+  writeIndex({ e: epic() });
+  fs.mkdirSync(path.join(path.dirname(projFile(wtDir)), SID, 'tool-results'), { recursive: true });
+  put(projFile(cwd));
+  const r = resolve();
+  expect(r.path).toBe(projFile(cwd));
+  expect(r.existingPaths).toEqual([projFile(cwd)]);
+});
+
+test('a directory named <id>.jsonl is not a transcript', () => {
+  writeIndex({ e: epic() });
+  fs.mkdirSync(projFile(wtDir), { recursive: true });
+  expect(resolve().existsAnywhere).toBe(false);
+});
+
+test('zero-byte file counts as existing but loses to a non-empty one', () => {
+  fs.mkdirSync(wtDir, { recursive: true });
+  writeIndex({ e: epic() });
+  put(projFile(wtDir), '');
+  let r = resolve();
+  expect(r.existsAnywhere).toBe(true);
+  expect(r.path).toBe(projFile(wtDir));
+  put(projFile(cwd), '{"a":1}\n', 1000);
+  r = resolve();
+  expect(r.path).toBe(projFile(cwd));
+  expect(r.existingPaths.length).toBe(2);
+});
+
+test('duplicate under two encodings: newest mtime wins', () => {
+  fs.mkdirSync(wtDir, { recursive: true });
+  writeIndex({ e: epic() });
+  put(projFile(wtDir), 'x\n', 2000);
+  put(projFile(cwd), 'x\n', 3000);
+  let r = resolve();
+  expect(r.existingPaths.length).toBe(2);
+  expect(r.path).toBe(projFile(cwd));
+  put(projFile(wtDir), 'x\n', 4000);
+  r = resolve();
+  expect(r.path).toBe(projFile(wtDir));
+});
+
+test('completed Epic (absent from index) resolved from its archive', () => {
+  writeIndex({});
+  fs.writeFileSync(path.join(promptDir(), 'done-epic-abcd1234.json'), JSON.stringify({ session: epic(), events: [], transcript: '', archivedAt: 'x' }));
+  put(projFile(wtDir));
+  const r = resolve();
+  expect(r.path).toBe(projFile(wtDir));
+});
+
+test('malformed archive JSON and unreadable index never throw', () => {
+  writeIndex({});
+  fs.writeFileSync(path.join(promptDir(), 'bad.json'), '{not json');
+  expect(() => resolve()).not.toThrow();
+  const r = resolve({ readActiveIndex: () => { throw new Error('boom'); } });
+  expect(r.candidates).toEqual([projFile(cwd)]);
+});
+
+test('blank/missing/unsafe inputs return a safe result', () => {
+  for (const args of [{}, { cwd: '', claudeSessionId: SID }, { cwd, claudeSessionId: '' }, { cwd, claudeSessionId: '../x' }]) {
+    const r = resolveEpicTranscriptPath({ ...args, deps: { homeDir: home } });
+    expect(r).toEqual({ path: null, candidates: [], existsAnywhere: false, existingPaths: [] });
+  }
+});
+
+test('index read once across N calls when unchanged; re-read after a touch', () => {
+  writeIndex({ e: epic() });
+  let reads = 0;
+  const deps = { readActiveIndex: (c) => { reads++; return readActiveIndex(c); } };
+  for (let i = 0; i < 20; i++) resolve(deps);
+  expect(reads).toBe(1);
+  writeIndex({ e: epic(), f: epic({ id: 'epic-2', claudeSessionId: 'zzz' }) });
+  resolve(deps);
+  expect(reads).toBe(2);
+});

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

@@ -147,8 +147,12 @@ test('SM_DEV=1 writes to a dev-suffixed path, never the production admin-api.jso
     expect(parsed.port).toBe(port);
     expect(parsed.token).toBe(token);
     // Production file must be untouched by the dev-mode instance.
+    // Content, not mtime: a live Session Manager on this machine legitimately rewrites the real
+    // admin-api.json at any moment (mtime drifted 12ms mid-test under load). What must hold is
+    // that THIS dev instance never wrote its port/token there.
     if (prevMtime !== null) {
-      expect(fs.statSync(TOKEN_PATH).mtimeMs).toBe(prevMtime);
+      const prod = JSON.parse(fs.readFileSync(TOKEN_PATH, 'utf8'));
+      expect(prod.token).not.toBe(token);
     } else {
       expect(fs.existsSync(TOKEN_PATH)).toBe(false);
     }

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

@@ -68,8 +68,47 @@ test('resolver and KIND_CONFIG roots follow SM_WORKTREE_ROOT together', () => {
   expect(schedulerPaths.worktreeRoot('epic')).toBe(path.join(override, 'session-manager-epic-worktrees'));
   expect(gitWorktree.KIND_CONFIG.job.root).toBe(schedulerPaths.worktreeRoot('job'));
   expect(gitWorktree.KIND_CONFIG.epic.root).toBe(schedulerPaths.worktreeRoot('epic'));
+});
+
+test('unset SM_WORKTREE_ROOT resolves the persistent per-user dir (0700, created), never os.tmpdir()', () => {
+  const state = path.join(scratch, 'state');
+  const prevXdg = process.env.XDG_STATE_HOME;
+  process.env.XDG_STATE_HOME = state;
   delete process.env.SM_WORKTREE_ROOT;
-  expect(schedulerPaths.worktreeRoot('job')).toBe(path.join(os.tmpdir(), 'session-manager-job-worktrees'));
+  try {
+    // scratch lives under os.tmpdir(), so the state dir passes the (unchanged) guard as a tmp child.
+    const base = schedulerPaths.worktreeBase();
+    expect(base).toBe(path.join(state, 'session-manager'));
+    expect(base).not.toBe(os.tmpdir());
+    expect(fs.statSync(base).mode & 0o777).toBe(0o700);
+    expect(schedulerPaths.worktreeRoot('epic')).toBe(path.join(base, 'session-manager-epic-worktrees'));
+  } finally {
+    if (prevXdg === undefined) delete process.env.XDG_STATE_HOME; else process.env.XDG_STATE_HOME = prevXdg;
+  }
+});
+
+test('the vitest guard still throws for a live default (no SM_WORKTREE_ROOT, real ~/.local/state) and creates nothing', () => {
+  const prevXdg = process.env.XDG_STATE_HOME;
+  delete process.env.XDG_STATE_HOME;
+  delete process.env.SM_WORKTREE_ROOT;
+  const prevHome = process.env.HOME;
+  const fakeHome = path.join(scratch, 'nohome');
+  process.env.HOME = '/nonexistent-live-home-for-guard-test';
+  try {
+    expect(() => schedulerPaths.worktreeBase()).toThrow(/live root/);
+    expect(fs.existsSync(path.join(fakeHome, '.local'))).toBe(false);
+  } finally {
+    process.env.HOME = prevHome;
+    if (prevXdg !== undefined) process.env.XDG_STATE_HOME = prevXdg;
+  }
+});
+
+test('SM_WORKTREE_ROOT set wins over the persistent default', () => {
+  process.env.XDG_STATE_HOME = path.join(scratch, 'ignored');
+  try {
+    expect(schedulerPaths.worktreeBase()).toBe(override);
+    expect(fs.existsSync(path.join(scratch, 'ignored'))).toBe(false);
+  } finally { delete process.env.XDG_STATE_HOME; }
 });
 
 test('create / sweep / isEphemeralCwd operate under the override, never the real root', async () => {