claude-code-session-manager 0.88.1 → 0.90.0

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

@@ -1310,3 +1310,175 @@ test('[guard][epic] integrateEpicBranch inherits the same guard and still merges
 
   await gitWorktree.cleanupEpicWorktree({ cwd: repoCwd, dir: worktree.dir, branch: worktree.branch });
 });
+
+// ── integrateBranch failure subtype classification (mc-01) ──
+
+test('[job] integrateBranch classifies a dirty different tracked file as failureKind blocking_paths', async () => {
+  const slug = 'test-slug-kind-blocking';
+  const worktree = await gitWorktree.createJobWorktree({ cwd: repoCwd, slug });
+  expect(worktree.ok).toBe(true);
+
+  fs.writeFileSync(path.join(worktree.dir, 'README.md'), 'job edit\n', 'utf8');
+  git(['add', '-A'], worktree.dir);
+  git(['commit', '-q', '-m', 'job edits README'], worktree.dir);
+  // Dirty (uncommitted), byte-DIFFERENT edit in the main tree blocks the merge.
+  fs.writeFileSync(path.join(repoCwd, 'README.md'), 'different local edit\n', 'utf8');
+
+  const outcome = await gitWorktree.integrateJobBranch({ cwd: repoCwd, branch: worktree.branch, slug });
+  expect(outcome.ok).toBe(false);
+  expect(outcome.reason).toMatch(/merge failed \(likely a real content conflict\)/);
+  expect(outcome.failureKind).toBe('blocking_paths');
+  expect(outcome.blockingPaths.tracked).toEqual(['README.md']);
+  expect(outcome.blockingPaths.untracked).toEqual([]);
+
+  await gitWorktree.cleanupJobWorktree({ cwd: repoCwd, dir: worktree.dir, branch: worktree.branch, keepBranch: true });
+});
+
+test('[job] integrateBranch classifies diverging same-line commits as content_conflict with the conflicted path', async () => {
+  const slug = 'test-slug-kind-content';
+  const worktree = await gitWorktree.createJobWorktree({ cwd: repoCwd, slug });
+  expect(worktree.ok).toBe(true);
+
+  fs.writeFileSync(path.join(worktree.dir, 'README.md'), 'job edit\n', 'utf8');
+  git(['add', '-A'], worktree.dir);
+  git(['commit', '-q', '-m', 'job edits README'], worktree.dir);
+  fs.writeFileSync(path.join(repoCwd, 'README.md'), 'main tree edit\n', 'utf8');
+  git(['add', '-A'], repoCwd);
+  git(['commit', '-q', '-m', 'main tree edits README'], repoCwd);
+
+  const outcome = await gitWorktree.integrateJobBranch({ cwd: repoCwd, branch: worktree.branch, slug });
+  expect(outcome.ok).toBe(false);
+  expect(outcome.failureKind).toBe('content_conflict');
+  expect(outcome.conflictedPaths).toEqual(['README.md']);
+  // The abort still ran.
+  expect(fs.existsSync(path.join(repoCwd, '.git', 'MERGE_HEAD'))).toBe(false);
+  expect(git(['status', '--porcelain'], repoCwd).trim()).toBe('');
+
+  await gitWorktree.cleanupJobWorktree({ cwd: repoCwd, dir: worktree.dir, branch: worktree.branch, keepBranch: true });
+});
+
+test('[job] integrateBranch classifies disjoint appends to the END of one file as content_conflict when the path is not allowlisted (.js)', async () => {
+  const slug = 'test-slug-kind-append';
+  fs.writeFileSync(path.join(repoCwd, 'src.js'), '// intro\n', 'utf8');
+  git(['add', '-A'], repoCwd);
+  git(['commit', '-q', '-m', 'add src.js'], repoCwd);
+  const worktree = await gitWorktree.createJobWorktree({ cwd: repoCwd, slug });
+  expect(worktree.ok).toBe(true);
+
+  fs.appendFileSync(path.join(worktree.dir, 'src.js'), '\n// Section Six\nsix body\n', 'utf8');
+  git(['add', '-A'], worktree.dir);
+  git(['commit', '-q', '-m', 'job appends section six'], worktree.dir);
+  fs.appendFileSync(path.join(repoCwd, 'src.js'), '\n## Section Seven\nseven body\n\n## Section Ten\nten body\n', 'utf8');
+  git(['add', '-A'], repoCwd);
+  git(['commit', '-q', '-m', 'main appends sections seven and ten'], repoCwd);
+
+  const outcome = await gitWorktree.integrateJobBranch({ cwd: repoCwd, branch: worktree.branch, slug });
+  expect(outcome.ok).toBe(false);
+  expect(outcome.failureKind).toBe('content_conflict');
+  expect(outcome.conflictedPaths).toEqual(['src.js']);
+
+  await gitWorktree.cleanupJobWorktree({ cwd: repoCwd, dir: worktree.dir, branch: worktree.branch, keepBranch: true });
+});
+
+// ── pure-addition merge-conflict auto-resolve (mc-02) ──
+
+async function conflictScenario(slug, { base, side, main }) {
+  for (const [f, c] of Object.entries(base)) {
+    fs.mkdirSync(path.dirname(path.join(repoCwd, f)), { recursive: true });
+    fs.writeFileSync(path.join(repoCwd, f), c, 'utf8');
+  }
+  git(['add', '-A'], repoCwd);
+  git(['commit', '-q', '-m', 'base files'], repoCwd);
+  const worktree = await gitWorktree.createJobWorktree({ cwd: repoCwd, slug });
+  expect(worktree.ok).toBe(true);
+  for (const [f, c] of Object.entries(side)) {
+    fs.mkdirSync(path.dirname(path.join(worktree.dir, f)), { recursive: true });
+    fs.writeFileSync(path.join(worktree.dir, f), c, 'utf8');
+  }
+  git(['add', '-A'], worktree.dir);
+  git(['commit', '-q', '-m', 'job side'], worktree.dir);
+  for (const [f, c] of Object.entries(main)) {
+    fs.mkdirSync(path.dirname(path.join(repoCwd, f)), { recursive: true });
+    fs.writeFileSync(path.join(repoCwd, f), c, 'utf8');
+  }
+  git(['add', '-A'], repoCwd);
+  git(['commit', '-q', '-m', 'main side'], repoCwd);
+  return worktree;
+}
+
+const MARKER_RE = /^(<<<<<<<|\|\|\|\|\|\|\||=======|>>>>>>>)/m;
+
+test('[job] integrateBranch auto-resolves a pure-addition .md conflict by concatenating ours then theirs', async () => {
+  const slug = 'test-slug-pure-add';
+  const worktree = await conflictScenario(slug, {
+    base: { 'd.md': '# Doc\n\nintro\n' },
+    side: { 'd.md': '# Doc\n\nintro\n\n## Section A\na body\n' },
+    main: { 'd.md': '# Doc\n\nintro\n\n## Section B\nb body\n\n## Section C\nc body\n' },
+  });
+  const outcome = await gitWorktree.integrateJobBranch({ cwd: repoCwd, branch: worktree.branch, slug });
+  expect(outcome.ok).toBe(true);
+  expect(outcome.autoResolved).toBe('pure_addition_concat');
+  expect(outcome.resolvedPaths).toEqual(['d.md']);
+  const merged = fs.readFileSync(path.join(repoCwd, 'd.md'), 'utf8');
+  expect(merged).toBe('# Doc\n\nintro\n\n## Section B\nb body\n\n## Section C\nc body\n\n## Section A\na body\n');
+  expect(merged).not.toMatch(MARKER_RE);
+  expect(git(['status', '--porcelain'], repoCwd).trim()).toBe('');
+  expect(git(['log', '-1', '--format=%s'], repoCwd).trim()).toBe(`merge scheduler job ${slug}`);
+  expect(git(['rev-list', '--parents', '-n', '1', 'HEAD'], repoCwd).trim().split(' ').length).toBe(3);
+
+  await gitWorktree.cleanupJobWorktree({ cwd: repoCwd, dir: worktree.dir, branch: worktree.branch });
+});
+
+test('[job] integrateBranch does NOT auto-resolve a same-line .md edit and leaves the tree clean', async () => {
+  const slug = 'test-slug-pure-add-neg-sameline';
+  const worktree = await conflictScenario(slug, {
+    base: { 'd.md': 'intro\nORIGINAL LINE\n' },
+    side: { 'd.md': 'intro\nSIDE EDIT\n' },
+    main: { 'd.md': 'intro\nMAIN EDIT\n' },
+  });
+  const outcome = await gitWorktree.integrateJobBranch({ cwd: repoCwd, branch: worktree.branch, slug });
+  expect(outcome.ok).toBe(false);
+  expect(outcome.autoResolved).toBeUndefined();
+  expect(outcome.failureKind).toBe('content_conflict');
+  expect(outcome.conflictedPaths).toEqual(['d.md']);
+  expect(fs.readFileSync(path.join(repoCwd, 'd.md'), 'utf8')).toBe('intro\nMAIN EDIT\n');
+  expect(git(['status', '--porcelain'], repoCwd).trim()).toBe('');
+
+  await gitWorktree.cleanupJobWorktree({ cwd: repoCwd, dir: worktree.dir, branch: worktree.branch, keepBranch: true });
+});
+
+test('[job] integrateBranch does NOT auto-resolve a pure-addition conflict on a non-allowlisted path', async () => {
+  const slug = 'test-slug-pure-add-neg-js';
+  const worktree = await conflictScenario(slug, {
+    base: { 'src/thing.js': '// intro\n' },
+    side: { 'src/thing.js': '// intro\n// A\n' },
+    main: { 'src/thing.js': '// intro\n// B\n// C\n' },
+  });
+  const outcome = await gitWorktree.integrateJobBranch({ cwd: repoCwd, branch: worktree.branch, slug });
+  expect(outcome.ok).toBe(false);
+  expect(outcome.autoResolved).toBeUndefined();
+  expect(outcome.failureKind).toBe('content_conflict');
+  expect(fs.readFileSync(path.join(repoCwd, 'src/thing.js'), 'utf8')).toBe('// intro\n// B\n// C\n');
+  expect(git(['status', '--porcelain'], repoCwd).trim()).toBe('');
+
+  await gitWorktree.cleanupJobWorktree({ cwd: repoCwd, dir: worktree.dir, branch: worktree.branch, keepBranch: true });
+});
+
+test('[job] integrateBranch bails the whole merge when only some conflicted paths are provable (mixed .md + .js)', async () => {
+  const slug = 'test-slug-pure-add-neg-mixed';
+  const worktree = await conflictScenario(slug, {
+    base: { 'd.md': 'intro\n', 'src/thing.js': 'ORIGINAL\n' },
+    side: { 'd.md': 'intro\n## A\n', 'src/thing.js': 'SIDE\n' },
+    main: { 'd.md': 'intro\n## B\n', 'src/thing.js': 'MAIN\n' },
+  });
+  const outcome = await gitWorktree.integrateJobBranch({ cwd: repoCwd, branch: worktree.branch, slug });
+  expect(outcome.ok).toBe(false);
+  expect(outcome.autoResolved).toBeUndefined();
+  expect(outcome.conflictedPaths).toEqual(['d.md', 'src/thing.js']);
+  expect(fs.readFileSync(path.join(repoCwd, 'd.md'), 'utf8')).toBe('intro\n## B\n');
+  expect(fs.readFileSync(path.join(repoCwd, 'src/thing.js'), 'utf8')).toBe('MAIN\n');
+  expect(git(['status', '--porcelain'], repoCwd).trim()).toBe('');
+  expect(fs.existsSync(path.join(repoCwd, '.git', 'MERGE_HEAD'))).toBe(false);
+
+  await gitWorktree.cleanupJobWorktree({ cwd: repoCwd, dir: worktree.dir, branch: worktree.branch, keepBranch: true });
+});

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 () => {

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

@@ -80,11 +80,14 @@ test('every counter event still yields appVersion + machineDigest once persisted
   counters.trackEpicCreate(deps);
   counters.trackSchedulerJobFinish({ status: 'completed' }, deps);
 
-  // track() ingress does real (albeit fast) fs I/O before it resolves; wait a
-  // tick since the counter functions fire it without awaiting the promise.
-  await new Promise((r) => setTimeout(r, 50));
-
-  const recs = await readQueueLines(client);
+  // track() ingress does real fs I/O and the counter functions fire it without
+  // awaiting the promise, so poll (bounded) for all 4 records rather than a fixed
+  // sleep — a fixed 50ms lost the race under CPU contention.
+  let recs = [];
+  for (let i = 0; i < 200 && recs.length < 4; i++) {
+    await new Promise((r) => setTimeout(r, 25));
+    recs = await readQueueLines(client);
+  }
   expect(recs.length).toBe(4);
   for (const rec of recs) {
     const meta = asPersistedMetadata(rec);

package/src/main/lib/effectiveModelInfo.cjs

@@ -27,7 +27,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
 const { splitFrontmatter } = require('./prdFrontmatter.cjs');
-const { encodeCwd } = require('./encodeCwd.cjs');
+const { resolveEpicTranscriptPath } = require('./epicTranscriptPath.cjs');
 
 // Mirrors rawSessionModel.ts's RAW_MODELS — duplicated rather than imported
 // because that file is a renderer ES module and this is a main-process CJS
@@ -252,10 +252,10 @@ function findLatestTranscriptModel(cwd, agentType, deps) {
   matches.sort((a, b) => (Date.parse(b.createdAt || 0) || 0) - (Date.parse(a.createdAt || 0) || 0));
 
   const homeDir = deps.homeDir || os.homedir();
-  const encodeCwdFn = deps.encodeCwd || encodeCwd;
   const re = /"model":"([^"]+)"/g;
   for (const session of matches) {
-    const filePath = path.join(homeDir, '.claude', 'projects', encodeCwdFn(cwd), `${session.claudeSessionId}.jsonl`);
+    const filePath = resolveEpicTranscriptPath({ cwd, claudeSessionId: session.claudeSessionId, deps: { homeDir } }).path;
+    if (!filePath) continue;
     const tail = readTail(filePath, MAX_TRANSCRIPT_TAIL_BYTES, deps);
     if (!tail) continue;
     let match;

package/src/main/lib/epicDelegationStats.cjs

@@ -27,7 +27,7 @@
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
-const { encodeCwd } = require('./encodeCwd.cjs');
+const { resolveEpicTranscriptPath } = require('./epicTranscriptPath.cjs');
 const { classifyLine } = require('./classifyTranscriptLine.cjs');
 
 // Same cap transcripts.cjs's readDelta uses for a single pass — bounds
@@ -85,7 +85,8 @@ function countInlineEdits(cwd, claudeSessionId, deps = {}) {
   const readFn = deps.readTranscriptTail || readTranscriptTail;
   const homeDir = deps.homeDir || os.homedir();
   try {
-    const filePath = path.join(homeDir, '.claude', 'projects', encodeCwd(cwd), `${claudeSessionId}.jsonl`);
+    const filePath = resolveEpicTranscriptPath({ cwd, claudeSessionId, deps: { homeDir } }).path;
+    if (!filePath) return 0;
     const text = readFn(filePath, deps);
     let count = 0;
     for (const line of text.split('\n')) {

package/src/main/lib/epicSpawnCwd.cjs

@@ -27,6 +27,8 @@
  */
 
 const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
 const { readActiveIndex } = require('./epicMint.cjs');
 
 /**
@@ -61,6 +63,26 @@ function isUsableDir(dir, statImpl) {
   }
 }
 
+/**
+ * Re-attach `branch` at `dir` (`git worktree add`). Sync + bounded; never throws. `dir` comes from
+ * a git-tracked file, so it is only honoured when it sits in a `session-manager-epic-worktrees`
+ * segment and the branch is an `sm-epic/` one — nothing else may be materialised from that record.
+ * @returns {boolean} true when `dir` now exists as a checkout.
+ */
+function restoreEpicWorktree({ dir, branch, baseCwd }) {
+  try {
+    if (!path.isAbsolute(dir) || !path.isAbsolute(baseCwd)) return false;
+    if (!path.resolve(dir).split(path.sep).includes('session-manager-epic-worktrees')) return false;
+    if (typeof branch !== 'string' || !/^sm-epic\/[A-Za-z0-9._-]+$/.test(branch)) return false;
+    const run = (args) => execFileSync('git', args, { cwd: baseCwd, stdio: 'ignore', timeout: 15_000 });
+    run(['worktree', 'prune']);
+    run(['worktree', 'add', dir, branch]);
+    return isUsableDir(dir, fs.statSync);
+  } catch {
+    return false;
+  }
+}
+
 /**
  * @param {{ cwd: string, claudeSessionId: string, deps?: object }} opts
  * @returns {string} `worktree.dir` when the matching Epic has one AND it still
@@ -77,10 +99,19 @@ function resolveEpicSpawnCwd({ cwd, claudeSessionId, deps = {} } = {}) {
         const dir = session.worktree?.dir;
         if (!dir) return cwd;
         if (!isUsableDir(dir, statSync)) {
-          // Falling back is strictly better than failing the spawn: the
-          // session still runs, just un-isolated, which is the same degraded
-          // mode a project that never had a worktree runs in.
-          console.log(`[epicSpawnCwd] worktree dir gone (${dir}) — falling back to ${cwd}`);
+          // NEVER fall back to the project cwd: the CLI files the transcript under
+          // encodeCwd(spawn cwd), so a resumed session started in a different dir splits
+          // its transcript across two encodings ("lost session"). Instead re-attach the
+          // Epic's own branch at the SAME recorded path (encoding unchanged); if that is
+          // impossible, return the recorded dir anyway so the spawn fails loudly (ENOENT)
+          // rather than silently forking the transcript. Read-side callers (no `restore`)
+          // keep the old cwd answer — they never spawn and must never mutate git state.
+          if (deps.restore) {
+            const restored = (deps.restoreWorktree || restoreEpicWorktree)({ dir, branch: session.worktree?.branch, baseCwd: cwd });
+            console.log(`[epicSpawnCwd] worktree dir gone (${dir}) — ${restored ? 'restored at same path' : 'restore failed; spawn will fail rather than split the transcript'}`);
+            return dir;
+          }
+          console.log(`[epicSpawnCwd] worktree dir gone (${dir}) — read-side falls back to ${cwd}`);
           return cwd;
         }
         return dir;
@@ -92,4 +123,4 @@ function resolveEpicSpawnCwd({ cwd, claudeSessionId, deps = {} } = {}) {
   return cwd;
 }
 
-module.exports = { resolveEpicSpawnCwd };
+module.exports = { resolveEpicSpawnCwd, restoreEpicWorktree };

package/src/main/lib/epicSpawnPlan.cjs

@@ -0,0 +1,119 @@
+'use strict';
+
+/**
+ * epicSpawnPlan.cjs — decides the spawn cwd AND the --resume/--session-id flag for an Epic's
+ * chat run TOGETHER (PRD 1319). They used to be computed independently: the flag from "does a
+ * transcript exist under ANY encoding" and the cwd separately, so a transcript stranded under a
+ * swept /tmp worktree encoding produced `--resume` from a cwd that cannot see it ("No
+ * conversation found"), the flag-swap retry then hit `--session-id` ("already in use"), and both
+ * doors were locked.
+ *
+ * Chosen fix: (a) first — resolveEpicSpawnCwd({restore:true}) re-attaches the Epic's own branch
+ * at the SAME recorded path (encoding unchanged), so the CLI sees the transcript again. When that
+ * is impossible, (b): refuse BEFORE spawning with an actionable message naming the missing
+ * worktree path, never claim a flag that cannot work. Reachability = "some existing transcript
+ * lives under encodeCwd(spawn cwd)" and the spawn cwd is a real directory.
+ *
+ * Also refuses requests routed to a closed (`completed`) Epic, and keeps a per-session circuit
+ * breaker: once a session is found unreachable, later requests are refused after ONE stat (is the
+ * worktree dir still missing?) without re-running the restore git commands.
+ *
+ * Ops-root hazard (epicSpawnCwd.cjs): `execCwd` returned here is for the spawn cwd option ONLY;
+ * ops reads/writes keep using the project `cwd` (projectRootOf / resolveProjectRoot).
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { encodeCwd } = require('./encodeCwd.cjs');
+const { readActiveIndex } = require('./epicMint.cjs');
+const { resolveEpicSpawnCwd } = require('./epicSpawnCwd.cjs');
+const { resolveEpicTranscriptPath } = require('./epicTranscriptPath.cjs');
+
+/** Map<sessionId, { dir, message }> — sessions found unreachable; valid while `dir` stays missing. */
+const unreachable = new Map();
+
+function __resetForTests() {
+  unreachable.clear();
+}
+
+function isDir(dir, statSync) {
+  try {
+    return statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** The Epic record for a session id: active-index first, else a bounded scan of archived `<id>.json`. */
+function findEpic(cwd, claudeSessionId, deps) {
+  try {
+    for (const s of Object.values((deps.readActiveIndex || readActiveIndex)(cwd).sessions || {})) {
+      if (s && s.claudeSessionId === claudeSessionId) return s;
+    }
+  } catch { /* unreadable index → try archives */ }
+  try {
+    const { opsPath } = require('./opsOwnership.cjs');
+    const dir = opsPath(cwd, 'prompt-sessions');
+    for (const name of fs.readdirSync(dir)) {
+      if (!name.endsWith('.json') || name === 'active-index.json') continue;
+      try {
+        const s = JSON.parse(fs.readFileSync(path.join(dir, name), 'utf8'))?.session;
+        if (s && s.claudeSessionId === claudeSessionId) return s;
+      } catch { /* malformed archive */ }
+    }
+  } catch { /* no ops dir */ }
+  return null;
+}
+
+/**
+ * @param {{ cwd: string, claudeSessionId: string, fallbackResume?: boolean, deps?: object }} opts
+ * @returns {{ ok: true, execCwd: string, useResume: boolean, transcriptPath: string|null }
+ *   | { ok: false, code: 'epic_closed'|'session_unreachable', message: string }}
+ */
+function planEpicSpawn({ cwd, claudeSessionId, fallbackResume = false, deps = {} } = {}) {
+  const statSync = deps.statSync || fs.statSync;
+  const epic = findEpic(cwd, claudeSessionId, deps);
+
+  if (epic && epic.status === 'completed') {
+    return {
+      ok: false,
+      code: 'epic_closed',
+      message: `This Epic is closed (completed) — it no longer accepts requests. Start a new Epic instead of routing work into session ${claudeSessionId}.`,
+    };
+  }
+
+  const brokenDir = epic?.worktree?.dir;
+  const tripped = unreachable.get(claudeSessionId);
+  if (tripped && !isDir(tripped.dir, statSync)) return { ok: false, code: 'session_unreachable', message: tripped.message };
+  unreachable.delete(claudeSessionId);
+
+  let useResume = !!fallbackResume;
+  let resolved = null;
+  try {
+    resolved = resolveEpicTranscriptPath({ cwd, claudeSessionId, deps });
+    useResume = !!resolved.existsAnywhere;
+  } catch { /* keep the caller-supplied flag */ }
+
+  const execCwd = (deps.resolveSpawnCwd || resolveEpicSpawnCwd)({ cwd, claudeSessionId, deps: { restore: true, readActiveIndex: deps.readActiveIndex, statSync: deps.statSync, restoreWorktree: deps.restoreWorktree } });
+
+  if (resolved && resolved.existsAnywhere) {
+    const projectsDir = path.join(deps.homeDir || os.homedir(), '.claude', 'projects');
+    const home = path.join(projectsDir, encodeCwd(execCwd));
+    const reachable = isDir(execCwd, statSync) && resolved.existingPaths.some((p) => path.dirname(p) === home);
+    if (!reachable) {
+      const missing = brokenDir || execCwd;
+      const message =
+        `Session ${claudeSessionId} cannot be resumed: its transcript is at ${resolved.existingPaths[0]}, ` +
+        `which the CLI only finds when run from ${missing}, and that worktree no longer exists and could not be ` +
+        `re-attached (likely swept from /tmp). Recreate it (git worktree add "${missing}" ${epic?.worktree?.branch || '<sm-epic branch>'}) ` +
+        `or start a new Epic.`;
+      unreachable.set(claudeSessionId, { dir: missing, message });
+      return { ok: false, code: 'session_unreachable', message };
+    }
+  }
+
+  return { ok: true, execCwd, useResume, transcriptPath: resolved?.path ?? null };
+}
+
+module.exports = { planEpicSpawn, __resetForTests };

package/src/main/lib/epicTranscriptDiagnostic.cjs

@@ -0,0 +1,79 @@
+'use strict';
+
+/**
+ * epicTranscriptDiagnostic.cjs — read-only scan for Epics whose claude
+ * transcript is not where the project-scoped lookup would put it.
+ *
+ *   mislocated — exactly one transcript exists and it is not under
+ *                <encodeCwd(project cwd)> (i.e. only a worktree encoding).
+ *   duplicated — the same session id has transcripts under 2+ encodings; the
+ *                state in which `claude --resume` fails from any third cwd.
+ *
+ * Bounded: walks Epic records of the supplied project cwds and stats each
+ * Epic's candidate paths via resolveEpicTranscriptPath. Never enumerates
+ * ~/.claude/projects. Writes nothing. Complexity: O(epics x candidates).
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { encodeCwd } = require('./encodeCwd.cjs');
+const { readActiveIndex } = require('./epicMint.cjs');
+const { opsPath } = require('./opsOwnership.cjs');
+const { resolveEpicTranscriptPath } = require('./epicTranscriptPath.cjs');
+
+/** [epicId, session] pairs: active-index rows plus archived per-Epic `<id>.json` records. */
+function epicRecords(cwd) {
+  const out = new Map();
+  try {
+    for (const [id, s] of Object.entries(readActiveIndex(cwd).sessions || {})) out.set(id, s);
+  } catch { /* unreadable index → archives only */ }
+  let dir;
+  let names = [];
+  try {
+    dir = opsPath(cwd, 'prompt-sessions');
+    names = fs.readdirSync(dir);
+  } catch { /* no ops dir → skip */ }
+  for (const name of names) {
+    if (!name.endsWith('.json') || name === 'active-index.json') continue;
+    const id = name.slice(0, -5);
+    if (out.has(id)) continue;
+    try {
+      const s = JSON.parse(fs.readFileSync(path.join(dir, name), 'utf8'))?.session;
+      if (s && typeof s === 'object') out.set(id, s);
+    } catch { /* malformed record → skip */ }
+  }
+  return out;
+}
+
+/**
+ * @param {{ cwds: string[], homeDir?: string }} opts
+ * @returns {Array<{ sessionId: string, epicId: string, cwd: string, paths: string[], classification: 'mislocated'|'duplicated' }>}
+ */
+function scanEpicTranscripts({ cwds, homeDir = os.homedir() }) {
+  const findings = [];
+  const projectsDir = path.join(homeDir, '.claude', 'projects');
+  for (const cwd of cwds || []) {
+    const sessions = epicRecords(cwd);
+    const home = path.join(projectsDir, encodeCwd(cwd));
+    for (const [epicId, s] of sessions) {
+      const sessionId = s && s.claudeSessionId;
+      if (!sessionId || typeof sessionId !== 'string') continue;
+      let res;
+      try {
+        res = resolveEpicTranscriptPath({ cwd, claudeSessionId: sessionId, deps: { homeDir } });
+      } catch {
+        continue;
+      }
+      const paths = res.existingPaths;
+      if (paths.length > 1) {
+        findings.push({ sessionId, epicId, cwd, paths, classification: 'duplicated' });
+      } else if (paths.length === 1 && path.dirname(paths[0]) !== home) {
+        findings.push({ sessionId, epicId, cwd, paths, classification: 'mislocated' });
+      }
+    }
+  }
+  return findings;
+}
+
+module.exports = { scanEpicTranscripts };