claude-code-session-manager 0.92.1 → 0.94.0

package/src/main/__tests__/pty-epic-worktree-spawn-cwd.test.cjs

@@ -259,3 +259,24 @@ test('spawn() still refuses session_unreachable without any node-pty spawn', ()
   expect(result.pid).toBeNull();
   expect(result.error).toMatch(/cannot be resumed/);
 });
+
+test('planEpicSpawn with a REAL on-disk index: project-root caller resumes, vanished-worktree caller is refused spawn_cwd_missing', () => {
+  const { planEpicSpawn, __resetForTests } = require('../lib/epicSpawnPlan.cjs');
+  __resetForTests();
+  const projectRoot = fs.mkdtempSync(path.join(tmpHome, 'sm-plan-root-'));
+  const deadWt = path.join(os.tmpdir(), 'sm-plan-dead-worktree-xyz');
+  const sessionId = 'epic-session-root-probe';
+  writeActiveIndexWithWorktree(projectRoot, { epicId: 'epic-rp', claudeSessionId: sessionId, worktreeDir: deadWt });
+  const tdir = path.join(tmpHome, '.claude', 'projects', projectRoot.replace(/[^a-zA-Z0-9]/g, '-'));
+  fs.mkdirSync(tdir, { recursive: true });
+  fs.writeFileSync(path.join(tdir, `${sessionId}.jsonl`), '{"type":"user"}\n');
+  const deps = { homeDir: tmpHome, restoreWorktree: () => null };
+
+  expect(planEpicSpawn({ cwd: projectRoot, claudeSessionId: sessionId, deps }))
+    .toMatchObject({ ok: true, execCwd: projectRoot, useResume: true });
+  __resetForTests();
+  const refused = planEpicSpawn({ cwd: deadWt, claudeSessionId: sessionId, deps });
+  expect(refused).toMatchObject({ ok: false, code: 'spawn_cwd_missing' });
+  expect(refused.message).toContain(deadWt);
+  expect(refused.message).toMatch(/project cwd/);
+});

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

@@ -20,6 +20,8 @@ const {
   nextBackoffMs,
   shouldWarnFailureStreak,
   shouldEscalateFailureStreak,
+  restoreFailureStreakWarnedAt,
+  persistedStreakMinutes,
   BACKOFF_MAX_MS,
   FAILURE_STREAK_WARN_THRESHOLD,
   FAILURE_STREAK_ESCALATION_MS,
@@ -112,3 +114,15 @@ test('shouldEscalateFailureStreak: re-arms after a streak clears (lastEscalatedA
   const laterStreakNow = firstStreakNow + 5 * 60_000; // well under 30 min later
   expect(shouldEscalateFailureStreak(FAILURE_STREAK_WARN_THRESHOLD, null, laterStreakNow)).toBe(true);
 });
+
+test('restoreFailureStreakWarnedAt backfills now when warned=true has no numeric timestamp', () => {
+  expect(restoreFailureStreakWarnedAt(true, null, 5000)).toBe(5000);
+  expect(restoreFailureStreakWarnedAt(true, 1000, 5000)).toBe(1000);
+  expect(restoreFailureStreakWarnedAt(false, null, 5000)).toBeNull();
+});
+
+test('persistedStreakMinutes is always a number, never null', () => {
+  expect(persistedStreakMinutes(null, 5000)).toBe(0);
+  expect(persistedStreakMinutes(0, 120_000)).toBe(2);
+  expect(persistedStreakMinutes(restoreFailureStreakWarnedAt(true, undefined, 5000), 5000)).toBe(0);
+});

package/src/main/__tests__/runVerify-atomic-verdicts.test.cjs

@@ -0,0 +1,26 @@
+import { test, expect, vi } from 'vitest';
+const fs = require('node:fs');
+const path = require('node:path');
+const src = fs.readFileSync(path.join(__dirname, '..', 'runVerify.cjs'), 'utf8');
+
+test('verdicts sidecar write goes through config.writeJsonSync, not bare writeFileSync', () => {
+  expect(src).not.toMatch(/writeFileSync\(verdictsPath/);
+  expect(src).toMatch(/config\.cjs'\)\.writeJsonSync\(verdictsPath/);
+});
+
+test('conclude() invokes the atomic helper at runtime', async () => {
+  const config = require('../config.cjs');
+  const spy = vi.spyOn(config, 'writeJsonSync').mockReturnValue({ ok: true, mtimeMs: 0 });
+  const { verifyRun } = require('../runVerify.cjs');
+  const os = require('node:os');
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'rv-atomic-'));
+  try {
+    try {
+      await verifyRun({ queueEntry: { slug: 's' }, runDir: dir, prdPath: path.join(dir, 'none.md'), exitCode: 0 });
+    } catch { /* signature drift is fine; assert only on the spy */ }
+    expect(spy.mock.calls.some(([p]) => p === path.join(dir, 's.verdicts.json'))).toBe(true);
+  } finally {
+    spy.mockRestore();
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});

package/src/main/__tests__/runVerify-landed-commit-outranks.test.cjs

@@ -32,7 +32,7 @@
  * Run standalone: timeout 120 npx vitest run src/main/__tests__/runVerify-landed-commit-outranks.test.cjs
  */
 
-import { test } from 'vitest';
+import { test, beforeAll, afterAll, vi } from 'vitest';
 const assert = require('node:assert/strict');
 const os = require('node:os');
 const fs = require('node:fs');
@@ -40,6 +40,16 @@ const path = require('node:path');
 const { execFileSync } = require('node:child_process');
 const { verifyRun } = require('../runVerify.cjs');
 
+// Sidecar goes through config.writeJsonSync, whose allow-list rejects os.tmpdir() fixtures.
+let writeSpy;
+beforeAll(() => {
+  writeSpy = vi.spyOn(require('../config.cjs'), 'writeJsonSync').mockImplementation((abs, data) => {
+    require('node:fs').writeFileSync(abs, JSON.stringify(data, null, 2) + '\n');
+    return { ok: true, mtimeMs: 0 };
+  });
+});
+afterAll(() => writeSpy.mockRestore());
+
 const SLUG = '1218-fo-01-move-scripts-lib-into-src-main-lib';
 const FIXTURE_PATH = path.join(__dirname, 'fixtures', `${SLUG}.log`);
 const LANDED_COMMIT = 'd1edf15be50a783f08a55e6de328780f0feb3cb0';

package/src/main/__tests__/runVerify-transcript-commit-evidence.test.cjs

@@ -14,7 +14,7 @@
  * Run standalone: timeout 120 npx vitest run src/main/__tests__/runVerify-transcript-commit-evidence.test.cjs
  */
 
-import { test } from 'vitest';
+import { test, beforeAll, afterAll, vi } from 'vitest';
 const assert = require('node:assert/strict');
 const os = require('node:os');
 const fs = require('node:fs');
@@ -22,6 +22,16 @@ const path = require('node:path');
 const { execFileSync } = require('node:child_process');
 const { verifyRun } = require('../runVerify.cjs');
 
+// Sidecar goes through config.writeJsonSync, whose allow-list rejects os.tmpdir() fixtures.
+let writeSpy;
+beforeAll(() => {
+  writeSpy = vi.spyOn(require('../config.cjs'), 'writeJsonSync').mockImplementation((abs, data) => {
+    require('node:fs').writeFileSync(abs, JSON.stringify(data, null, 2) + '\n');
+    return { ok: true, mtimeMs: 0 };
+  });
+});
+afterAll(() => writeSpy.mockRestore());
+
 // ─── helpers (mirrors runVerify.test.cjs) ─────────────────────────────────────
 
 function makeTmpDir() {

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

@@ -19,7 +19,7 @@
  *      Expected: clean → null (caller may stamp 'completed')
  */
 
-import { test } from 'vitest';
+import { test, beforeAll, afterAll, vi } from 'vitest';
 const assert = require('node:assert/strict');
 const os = require('node:os');
 const fs = require('node:fs');
@@ -27,6 +27,17 @@ const path = require('node:path');
 const { execFileSync } = require('node:child_process');
 const { verifyRun, parseLog } = require('../runVerify.cjs');
 
+// The verdicts sidecar goes through config.writeJsonSync, whose write allow-list
+// rejects os.tmpdir() fixtures. Route it to a plain write for these fixtures.
+let writeSpy;
+beforeAll(() => {
+  writeSpy = vi.spyOn(require('../config.cjs'), 'writeJsonSync').mockImplementation((abs, data) => {
+    fs.writeFileSync(abs, JSON.stringify(data, null, 2) + '\n');
+    return { ok: true, mtimeMs: 0 };
+  });
+});
+afterAll(() => writeSpy.mockRestore());
+
 // ─── helpers ──────────────────────────────────────────────────────────────────
 
 /** Create a temp directory that is cleaned up after the test. */

package/src/main/__tests__/scheduler-prd-persona-spawn.test.cjs

@@ -82,8 +82,10 @@ function writePersona(dir, name, frontmatterLines, bodyText) {
   fs.writeFileSync(path.join(dir, `${name}.md`), lines.join('\n'));
 }
 
-async function runJobWithAgentType({ agentType }) {
-  const mainCwd = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-prd-persona-main-'));
+async function runJobWithAgentType({ agentType, overlay }) {
+  // Under tmpHome so config.validatePath's home-dir boundary admits the project overlay.
+  const mainCwd = fs.mkdtempSync(path.join(tmpHome, 'sm-prd-persona-main-'));
+  if (overlay) writePersona(path.join(mainCwd, '.claude', 'agents'), overlay.name, overlay.frontmatter, overlay.body || '');
   fs.mkdirSync(path.join(tmpHome, '.claude'), { recursive: true });
   const runDir = fs.mkdtempSync(path.join(tmpHome, '.claude', 'sm-prd-persona-run-'));
   const slug = `1115-test-${process.pid}-${Math.floor(Math.random() * 1e6)}`;
@@ -131,3 +133,46 @@ test('executeJob: a job with no agentType at all runs unaffected (no persona, so
   const modelIdx = argv.indexOf('--model');
   expect(argv[modelIdx + 1]).toBe('sonnet');
 });
+
+// ---------- persona effort → --effort ----------
+
+test('buildClaudeSpawnArgs: effort appends --effort <level>; null/inherit/absent add no token', () => {
+  const base = { prompt: 'x', model: 'sonnet', sessionId: 'sid', resume: false };
+  const args = buildClaudeSpawnArgs({ ...base, effort: 'high' });
+  expect(args[args.indexOf('--effort') + 1]).toBe('high');
+  expect(args.indexOf('--model')).toBeGreaterThanOrEqual(0);
+  for (const effort of [null, 'inherit', undefined]) {
+    expect(buildClaudeSpawnArgs({ ...base, effort })).not.toContain('--effort');
+  }
+});
+
+test('executeJob: persona effort reaches the child as --effort; inherit yields no --effort token', async () => {
+  const globalAgentsDir = path.join(tmpHome, '.claude', 'agents');
+  writePersona(globalAgentsDir, 'effort-high', ['model: opus', 'effort: high'], 'body');
+  writePersona(globalAgentsDir, 'effort-inherit', ['model: opus', 'effort: inherit'], 'body');
+
+  const high = await runJobWithAgentType({ agentType: 'effort-high' });
+  expect(high.argv[high.argv.indexOf('--effort') + 1]).toBe('high');
+  expect(high.argv[high.argv.indexOf('--model') + 1]).toBe('opus');
+
+  const inherit = await runJobWithAgentType({ agentType: 'effort-inherit' });
+  expect(inherit.argv).not.toContain('--effort');
+  expect(inherit.argv).not.toContain('inherit');
+});
+
+// ---------- project overlay MERGE: frontmatter-only overlay patches the runtime fields ----------
+
+test('executeJob: a frontmatter-only project overlay changes --model/--effort while the global persona body still reaches --append-system-prompt', async () => {
+  const globalAgentsDir = path.join(tmpHome, '.claude', 'agents');
+  writePersona(globalAgentsDir, 'dev-lead', ['model: sonnet'], 'You are dev-lead. Global body.');
+
+  const { result, argv } = await runJobWithAgentType({
+    agentType: 'dev-lead',
+    overlay: { name: 'dev-lead', frontmatter: ['model: claude-opus-4-6', 'effort: high'], body: '' },
+  });
+
+  expect(result.exitCode).toBe(0);
+  expect(argv[argv.indexOf('--model') + 1]).toBe('claude-opus-4-6');
+  expect(argv[argv.indexOf('--effort') + 1]).toBe('high');
+  expect(argv[argv.indexOf('--append-system-prompt') + 1]).toBe('You are dev-lead. Global body.');
+});

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

@@ -8,7 +8,7 @@
 
 'use strict';
 
-import { test, expect, beforeEach, afterEach } from 'vitest';
+import { test, expect, beforeEach, afterEach, vi } from 'vitest';
 
 const fs = require('node:fs');
 const os = require('node:os');
@@ -93,3 +93,114 @@ test('a growing transcript is re-summed after the file mtime/size change', async
   const after = await usageFor(cwd, [sessionId]);
   expect(after[sessionId]).toEqual({ inputTokens: 13, outputTokens: 6 });
 });
+
+// ── incremental tail parse + bounded cache ─────────────────────────────────
+
+const fsp = require('node:fs/promises');
+const transcripts = require('../transcripts.cjs');
+
+function fromScratch(filePath) {
+  let inputTokens = 0;
+  let outputTokens = 0;
+  for (const line of fs.readFileSync(filePath, 'utf8').split('\n')) {
+    if (!line) continue;
+    let o;
+    try { o = JSON.parse(line); } catch { continue; }
+    const u = o.usage || {};
+    inputTokens += u.input_tokens ?? 0;
+    outputTokens += u.output_tokens ?? 0;
+  }
+  return { inputTokens, outputTokens };
+}
+
+test('incremental result equals a from-scratch parse across 5 appends (partial line + repeated id)', async () => {
+  const sessionId = 'sess-incr';
+  const filePath = writeTranscript(cwd, sessionId, [
+    { id: 'm1', usage: { input_tokens: 10, output_tokens: 1 } },
+  ]);
+  const check = async () => {
+    const r = await usageFor(cwd, [sessionId]);
+    expect(r[sessionId]).toEqual(fromScratch(filePath));
+  };
+  await check();
+  const l2 = JSON.stringify({ id: 'm2', usage: { input_tokens: 20, output_tokens: 2 } });
+  // 1: append ending mid-line
+  fs.appendFileSync(filePath, l2.slice(0, 15));
+  await check();
+  // 2: complete that line
+  fs.appendFileSync(filePath, l2.slice(15) + '\n');
+  await check();
+  // 3: repeat an earlier message id (full parse sums it again)
+  fs.appendFileSync(filePath, JSON.stringify({ id: 'm1', usage: { input_tokens: 10, output_tokens: 1 } }) + '\n');
+  await check();
+  // 4: non-usage + malformed line
+  fs.appendFileSync(filePath, JSON.stringify({ type: 'user' }) + '\nnot json\n');
+  await check();
+  // 5: multibyte content then usage
+  fs.appendFileSync(filePath, JSON.stringify({ t: 'héllo 日本', usage: { input_tokens: 4, output_tokens: 4 } }) + '\n');
+  await check();
+  expect((await usageFor(cwd, [sessionId]))[sessionId]).toEqual({ inputTokens: 44, outputTokens: 8 });
+});
+
+test('the call after a one-line append reads < 4 KB from disk', async () => {
+  const sessionId = 'sess-bytes';
+  const big = Array.from({ length: 2000 }, (_, i) => ({ i, pad: 'x'.repeat(100), usage: { input_tokens: 1, output_tokens: 1 } }));
+  const filePath = writeTranscript(cwd, sessionId, big);
+  await usageFor(cwd, [sessionId]);
+  expect(fs.statSync(filePath).size).toBeGreaterThan(200_000);
+
+  fs.appendFileSync(filePath, JSON.stringify({ usage: { input_tokens: 5, output_tokens: 5 } }) + '\n');
+  const fh = await fsp.open(filePath, 'r');
+  const proto = Object.getPrototypeOf(fh);
+  await fh.close();
+  const orig = proto.read;
+  const lengths = [];
+  const spy = vi.spyOn(proto, 'read').mockImplementation(function (buf, off, len, pos) {
+    lengths.push(len);
+    return orig.call(this, buf, off, len, pos);
+  });
+  try {
+    const r = await usageFor(cwd, [sessionId]);
+    expect(r[sessionId]).toEqual({ inputTokens: 2005, outputTokens: 2005 });
+  } finally {
+    spy.mockRestore();
+  }
+  expect(lengths.length).toBeGreaterThan(0);
+  expect(lengths.reduce((a, b) => a + b, 0)).toBeLessThan(4096);
+});
+
+test('truncation / replacement triggers a full re-parse', async () => {
+  const sessionId = 'sess-trunc';
+  const filePath = writeTranscript(cwd, sessionId, [
+    { usage: { input_tokens: 100, output_tokens: 100 } },
+    { usage: { input_tokens: 100, output_tokens: 100 } },
+  ]);
+  await usageFor(cwd, [sessionId]);
+  fs.writeFileSync(filePath, JSON.stringify({ usage: { input_tokens: 1, output_tokens: 2 } }) + '\n');
+  expect((await usageFor(cwd, [sessionId]))[sessionId]).toEqual({ inputTokens: 1, outputTokens: 2 });
+});
+
+test('usageCache is bounded and evicts the least-recently-used entry', async () => {
+  const cache = transcripts.__usageCacheForTest;
+  const max = transcripts.__usageCacheMaxForTest;
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-usage-lru-'));
+  try {
+    const files = [];
+    for (let i = 0; i < max + 5; i++) {
+      const f = path.join(dir, `s${i}.jsonl`);
+      fs.writeFileSync(f, JSON.stringify({ usage: { input_tokens: 1, output_tokens: 1 } }) + '\n');
+      files.push(f);
+    }
+    const before = cache.size;
+    for (const f of files) {
+      // usageForOne is reached through usageFor's path; call via a cwd-independent route.
+      await transcripts.__usageForOneForTest(f);
+    }
+    expect(cache.size).toBeLessThanOrEqual(max);
+    expect(before).toBeLessThanOrEqual(max);
+    expect(cache.has(files[0])).toBe(false);
+    expect(cache.has(files[files.length - 1])).toBe(true);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});

package/src/main/agentLibrary.cjs

@@ -22,7 +22,7 @@ const fsSync = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
 const { splitFrontmatter } = require('./lib/prdFrontmatter.cjs');
-const { resolvePersonaPaths } = require('./lib/epicMint.cjs');
+const { resolveMergedPersona, PERSONA_NAME_RE } = require('./lib/personaMerge.cjs');
 const configMgr = require('./config.cjs');
 const sessionsStore = require('./sessionsStore.cjs');
 
@@ -32,9 +32,6 @@ function parseTools(raw) {
   return raw.split(',').map((t) => t.trim()).filter(Boolean);
 }
 
-/** Filename-safe persona name: lowercase, hyphenated, matches the `.md` files on disk. */
-const PERSONA_NAME_RE = /^[a-z][a-z0-9-]*$/;
-
 /** Sentinel `projects:` entry meaning "this agent's Action button shows in every project". */
 const ALL_PROJECTS = '*';
 
@@ -70,11 +67,12 @@ function decodeLine(s) {
  * overrides the button's caption (defaults to the persona name). Claude Code
  * ignores all three; only this app reads them.
  */
-function serializePersona({ name, description, tools, model, color, tags, projects, action, actionLabel, title, body }) {
+function serializePersona({ name, description, tools, model, effort, color, tags, projects, action, actionLabel, title, body }) {
   const lines = ['---', `name: ${name}`];
   if (description) lines.push(`description: ${description}`);
   if (tools && tools.length) lines.push(`tools: ${tools.join(', ')}`);
   if (model && model !== 'inherit') lines.push(`model: ${model}`);
+  if (effort && effort !== 'inherit') lines.push(`effort: ${effort}`);
   if (color) lines.push(`color: ${color}`);
   if (tags && tags.length) lines.push(`tags: ${tags.join(', ')}`);
   if (projects && projects.length) lines.push(`projects: ${projects.join(', ')}`);
@@ -85,10 +83,51 @@ function serializePersona({ name, description, tools, model, color, tags, projec
   return lines.join('\n') + (body || '').trim() + '\n';
 }
 
+/**
+ * Project OVERRIDE write: a frontmatter-only overlay at
+ * `<cwd>/.claude/agents/<name>.md` carrying ONLY the overridden `model` /
+ * `effort` keys and no body (lib/personaMerge.cjs inherits everything else
+ * from the global persona). Keys already in an existing frontmatter-only
+ * overlay are preserved; an existing overlay that has a BODY is refused so a
+ * full-body overlay is never silently converted. Both keys unset removes the
+ * file (same as `removeOverride`) rather than leaving an empty overlay.
+ */
+async function saveOverlay({ name, projectName, model, effort, loadSessions, validatePath, writeTextAtomic }) {
+  const projects = await openProjects({ loadSessions });
+  const project = projects.find((p) => p.name === projectName);
+  if (!project) throw new Error(`project not open: ${projectName}`);
+  const target = validatePath(path.join(project.cwd, '.claude', 'agents', `${name}.md`));
+  let fm = {};
+  try {
+    const existing = splitFrontmatter(await fsp.readFile(target, 'utf8'));
+    if (existing.body.trim() !== '') {
+      throw new Error(`${name} has a full-body override in ${projectName} — edit ${target} directly; it is not converted to a frontmatter-only override`);
+    }
+    fm = existing.fm;
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw e;
+  }
+  const next = { ...fm };
+  for (const [k, v] of [['model', model], ['effort', effort]]) {
+    if (v && v !== 'inherit') next[k] = v;
+    else delete next[k];
+  }
+  if (Object.keys(next).length === 0) {
+    await removeOverride({ name, projectName, loadSessions, validatePath });
+    return { ok: true, path: target, removed: true };
+  }
+  const lines = ['---', ...Object.entries(next).map(([k, v]) => `${k}: ${v}`), '---', ''];
+  await writeTextAtomic(target, lines.join('\n'));
+  return { ok: true, path: target };
+}
+
 /**
  * Writes a global persona `.md` file — `~/.claude/agents/<name>.md`. Pass
  * `originalName` when renaming an existing persona so the old file is
- * removed once the new one is written (no-op if names match).
+ * removed once the new one is written (no-op if names match). Pass
+ * `projectName` (an open project) to instead write that project's
+ * frontmatter-only OVERRIDE of the persona — see saveOverlay; only `model` and
+ * `effort` are read in that mode.
  */
 async function savePersona({
   name,
@@ -96,6 +135,7 @@ async function savePersona({
   description,
   tools,
   model,
+  effort,
   color,
   tags,
   projects,
@@ -103,15 +143,20 @@ async function savePersona({
   actionLabel,
   title,
   body,
+  projectName,
   globalDir = path.join(os.homedir(), '.claude', 'agents'),
+  loadSessions = sessionsStore.load,
   validatePath = configMgr.validatePath,
   writeTextAtomic = configMgr.writeTextAtomic,
 } = {}) {
   if (!PERSONA_NAME_RE.test(name || '')) {
     throw new Error('agent name must be lowercase, hyphenated (e.g. "my-agent")');
   }
+  if (projectName) {
+    return saveOverlay({ name, projectName, model, effort, loadSessions, validatePath, writeTextAtomic });
+  }
   const target = validatePath(path.join(globalDir, `${name}.md`));
-  const text = serializePersona({ name, description, tools, model, color, tags, projects, action, actionLabel, title, body });
+  const text = serializePersona({ name, description, tools, model, effort, color, tags, projects, action, actionLabel, title, body });
   await writeTextAtomic(target, text);
   if (originalName && originalName !== name) {
     const oldReal = validatePath(path.join(globalDir, `${originalName}.md`));
@@ -220,6 +265,9 @@ async function listPersonas({
     const { fm, body } = splitFrontmatter(text);
 
     const overridingProjects = [];
+    // Per-project merged view: which frontmatter fields (and whether the body)
+    // the overlay actually overrides — from the shared merge, not a boolean.
+    const overrideDetails = [];
     for (const p of projects) {
       let overlayReal;
       try {
@@ -227,7 +275,18 @@ async function listPersonas({
       } catch {
         continue; // project cwd outside allowed roots — skip rather than throw
       }
-      if (fsSync.existsSync(overlayReal)) overridingProjects.push(p.name);
+      if (!fsSync.existsSync(overlayReal)) continue;
+      overridingProjects.push(p.name);
+      const merged = resolveMergedPersona(p.cwd, path.basename(file, '.md'), { validatePath, globalDir });
+      const fields = merged ? Object.keys(merged.provenance).filter((k) => merged.provenance[k] === 'overlay') : [];
+      overrideDetails.push({
+        project: p.name,
+        fields,
+        // The project's value for each overridden key (the UI renders global → project).
+        values: merged ? Object.fromEntries(fields.map((k) => [k, merged.fm[k]])) : {},
+        bodyOverridden: merged ? merged.bodySource === 'overlay' : false,
+        issue: merged ? merged.overlayIssue : null,
+      });
     }
 
     personas.push({
@@ -235,6 +294,7 @@ async function listPersonas({
       description: fm.description || null,
       tools: parseTools(fm.tools),
       model: fm.model || null,
+      effort: fm.effort || null,
       color: fm.color || null,
       tags: parseTools(fm.tags),
       projects: parseTools(fm.projects),
@@ -244,6 +304,7 @@ async function listPersonas({
       path: real,
       body: body.trim(),
       overridingProjects,
+      overrideDetails,
     });
   }
 
@@ -251,44 +312,29 @@ async function listPersonas({
 }
 
 /**
- * Reads a persona `.md` file's raw text for `epicIntake.ts`'s `agentBody`
- * input, honoring the same project-overlay-then-global precedence as
- * `epicMint.cjs`'s `resolvePersonaPaths` (a project's `<cwd>/.claude/agents/
- * <name>.md` wins over `~/.claude/agents/<name>.md`) — the same precedence
- * `listPersonas` deliberately does NOT apply, since that lists only the
- * global directory for the Agent Library nav page. Returns `null` when
- * neither location has the file; frontmatter stripping and the 6000-char cap
- * are epicIntake.ts's job, not this reader's.
+ * Reads a persona for `epicIntake.ts`'s `agentBody` input and the PRD spawn
+ * path, through the shared overlay-over-global MERGE (lib/personaMerge.cjs —
+ * see its header for the rules). Returns `{ path, text, fm, body, fromOverlay,
+ * bodySource, provenance, overlayIssue }` where `fm`/`body` are the MERGED
+ * view, `provenance[key]` says which frontmatter keys came from the overlay,
+ * and `text` is the body-source file's raw text (byte-identical to the
+ * pre-merge result for a full-body overlay) or a re-serialized merge for a
+ * frontmatter-only overlay. `listPersonas` deliberately does NOT apply this —
+ * it lists the global directory for the Agent Library nav page. Returns `null`
+ * when neither location has the file; frontmatter stripping and the 6000-char
+ * cap are epicIntake.ts's / agentModelResolve.cjs's job, not this reader's.
+ * (Sync fs inside an async signature: the merge module is shared with the
+ * synchronous model resolver.)
  */
 async function getPersonaBody({
   cwd,
   name,
   validatePath = configMgr.validatePath,
+  ...deps
 } = {}) {
-  // Same gate savePersona/deletePersona apply before touching a path built
-  // from `name` (agentLibrary.cjs's PERSONA_NAME_RE check) — without it a
-  // `name` like "../../other-project/CLAUDE" survives resolvePersonaPaths'
-  // plain path.join and validatePath's allowed-roots check (which only
-  // confirms the resolved path stays under the home dir / an opened
-  // project), letting any readable .md under those roots be read and
-  // forwarded into the Epic's opening prompt.
-  if (!PERSONA_NAME_RE.test(name || '')) return null;
-  const { projectPath, globalPath } = resolvePersonaPaths(cwd, name);
-  for (const candidate of [projectPath, globalPath]) {
-    let real;
-    try {
-      real = validatePath(candidate);
-    } catch {
-      continue;
-    }
-    try {
-      const text = await fsp.readFile(real, 'utf8');
-      return { path: real, text };
-    } catch {
-      continue;
-    }
-  }
-  return null;
+  // PERSONA_NAME_RE is enforced inside resolveMergedPersona (the traversal
+  // guard for "../../other-project/CLAUDE"-style names).
+  return resolveMergedPersona(cwd, name, { ...deps, validatePath });
 }
 
 module.exports = {

package/src/main/build-info.json

@@ -1,8 +1,8 @@
 {
-  "version": "0.92.1",
-  "gitSha": "cc3a80b2b9933e408e8effca99e550e3409b4d42",
-  "gitShortSha": "cc3a80b",
+  "version": "0.94.0",
+  "gitSha": "b5777198add78466da6d34b83d818bb1352f999a",
+  "gitShortSha": "b577719",
   "gitBranch": "HEAD",
-  "builtAt": "2026-09-20T22:38:10.510Z",
+  "builtAt": "2026-09-21T19:59:46.626Z",
   "dirty": false
 }