claude-code-session-manager 0.92.1 → 0.94.0

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

@@ -0,0 +1,69 @@
+/**
+ * gitCacheBound.test.cjs — git status caches are LRU-bounded and drop expired entries.
+ *
+ * Run: timeout 120 npx vitest run src/main/lib/__tests__/gitCacheBound.test.cjs
+ */
+'use strict';
+
+import { test, expect, beforeEach, afterEach, vi } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { addAllowedRoot } = require('../../config.cjs');
+const git = require('../../git.cjs');
+
+const { statusCache, fileStatusCache, CACHE_MAX_CWDS } = git._caches;
+let root;
+beforeEach(() => {
+  git.clearCache();
+  root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'git-cache-bound-')));
+  addAllowedRoot(root);
+});
+afterEach(() => {
+  vi.restoreAllMocks();
+  fs.rmSync(root, { recursive: true, force: true });
+});
+
+function mkdirs(n) {
+  return Array.from({ length: n }, (_, i) => {
+    const d = path.join(root, `d${i}`);
+    fs.mkdirSync(d);
+    return fs.realpathSync(d);
+  });
+}
+
+test('50 distinct cwds never exceed the cap', async () => {
+  for (const d of mkdirs(50)) {
+    await git.getStatus(d);
+    await git.getFileStatus(d);
+  }
+  expect(statusCache.size).toBeLessThanOrEqual(CACHE_MAX_CWDS);
+  expect(fileStatusCache.size).toBeLessThanOrEqual(CACHE_MAX_CWDS);
+  expect(statusCache.size).toBe(CACHE_MAX_CWDS);
+});
+
+test('an expired entry is deleted when encountered', async () => {
+  const [d] = mkdirs(1);
+  const t0 = 1_000_000;
+  const now = vi.spyOn(Date, 'now').mockReturnValue(t0);
+  await git.getStatus(d);
+  await git.getFileStatus(d);
+  expect(statusCache.get(d).expiresAt).toBe(t0 + 5_000);
+
+  // Live entry: served from cache, untouched.
+  now.mockReturnValue(t0 + 4_999);
+  await git.getStatus(d);
+  expect(statusCache.get(d).expiresAt).toBe(t0 + 5_000);
+
+  // Expired: the stale entry is deleted and replaced by a fresh one.
+  now.mockReturnValue(t0 + 60_000);
+  const del = vi.spyOn(statusCache, 'delete');
+  await git.getStatus(d);
+  expect(del).toHaveBeenCalledWith(d);
+  expect(statusCache.get(d).expiresAt).toBe(t0 + 65_000);
+
+  const delFile = vi.spyOn(fileStatusCache, 'delete');
+  await git.getFileStatus(d);
+  expect(delFile).toHaveBeenCalledWith(d);
+  expect(fileStatusCache.get(d).expiresAt).toBe(t0 + 65_000);
+});

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

@@ -0,0 +1,202 @@
+'use strict';
+import { describe, it, expect, vi } from 'vitest';
+const { resolveModelCatalog, CATALOG_FLOOR, parseAliases, parseEffortLevels, scanModelIds } = require('../modelCatalog.cjs');
+
+const MODEL_OUT = 'Usage: /model <name>. Available: sonnet, opus, haiku, fable, best, sonnet[1m], opus[1m], fable[1m], opusplan, default, or a full model ID.';
+const EFFORT_OUT = 'Usage: /effort <low|medium|high|xhigh|max|auto>';
+const NOW = Date.parse('2026-09-20T00:00:00Z');
+
+function mk(over = {}) {
+  const files = over.files || {};
+  const fsImpl = {
+    readFileSync: (f) => { if (f in files) return files[f]; if (String(f).endsWith('claude-settings-schema.json')) return JSON.stringify({ properties: { effortLevel: { enum: ['low', 'medium', 'high', 'xhigh'] } } }); throw new Error('ENOENT'); },
+    realpathSync: (p) => p,
+    statSync: () => ({ isFile: () => true, size: 200 * 1024 * 1024 }),
+    openSync: () => 1, readSync: (fd, buf) => { buf.write('\x7fELF'); return 4; }, closeSync: () => {},
+    ...over.fs,
+  };
+  const runClaudeP = vi.fn(async (prompt) => ({ ok: true, out: prompt === '/model' ? MODEL_OUT : EFFORT_OUT }));
+  const writeJson = vi.fn(async () => {});
+  const deps = {
+    env: {}, now: () => NOW, homeDir: () => '/home/u', projectRootOf: (c) => c,
+    probeClaudeVersion: async () => '2.1.277', resolveClaudeBin: () => '/bin/claude',
+    scanModelIds: () => ['claude-opus-5', 'claude-sonnet-5'], fs: fsImpl, runClaudeP, writeJson, ...over.deps,
+  };
+  return { deps, runClaudeP, writeJson };
+}
+const CACHE = '/home/u/.claude/session-manager/model-catalog.json';
+const cacheEntry = (o = {}) => JSON.stringify({ aliases: ['sonnet'], models: ['claude-old-1'], effortLevels: ['low'], settingsEffortLevels: ['low'], claudeVersion: '2.1.277', probedAt: new Date(NOW - 1000).toISOString(), degraded: false, ...o });
+
+describe('parsers', () => {
+  it('parses aliases, dropping the "or a full model ID" clause and keeping [1m]', () => {
+    expect(parseAliases(`Current model: x\n${MODEL_OUT}`)).toEqual(['sonnet', 'opus', 'haiku', 'fable', 'best', 'sonnet[1m]', 'opus[1m]', 'fable[1m]', 'opusplan', 'default']);
+  });
+  it('parses effort levels', () => {
+    expect(parseEffortLevels(EFFORT_OUT)).toEqual(['low', 'medium', 'high', 'xhigh', 'max', 'auto']);
+  });
+  it('returns null on garbage', () => {
+    expect(parseAliases('nope')).toBeNull();
+    expect(parseEffortLevels('nope')).toBeNull();
+  });
+});
+
+describe('scanModelIds', () => {
+  const scanBuf = (content, opts) => {
+    const data = Buffer.from(content, 'latin1');
+    let pos = 0;
+    const fsImpl = {
+      openSync: () => 1, closeSync: () => {},
+      readSync: (fd, buf, off, len) => { const n = Math.min(len, data.length - pos); data.copy(buf, off, pos, pos + n); pos += n; return n; },
+    };
+    return scanModelIds('/x', { fsImpl, ...opts });
+  };
+  it('finds an id split across a chunk boundary', () => {
+    const content = 'x'.repeat(13) + 'claude-opus-4-8' + '\0' + 'y'.repeat(20) + 'claude-haiku-4-5-20251001\0';
+    // chunk 20 cuts the first id after "claude-opus" (offset 13..28)
+    expect(scanBuf(content, { chunkSize: 20, overlap: 64 })).toEqual(['claude-haiku-4-5-20251001', 'claude-opus-4-8']);
+  });
+  it('does not report a truncated id when the tail is cut mid-number', () => {
+    expect(scanBuf('aaaaclaude-opus-4-8zz', { chunkSize: 14, overlap: 64 })).toEqual(['claude-opus-4-8']);
+  });
+});
+
+describe('resolveModelCatalog', () => {
+  it('happy path: merges probes, binary, schema, allowlist and writes cache', async () => {
+    const t = mk({ files: { '/home/u/.claude/settings.json': JSON.stringify({ availableModels: ['opus', 'haiku'] }), '/p/.claude/settings.local.json': JSON.stringify({ availableModels: ['haiku', 'sonnet'] }) } });
+    const c = await resolveModelCatalog({ cwd: '/p', force: true, deps: t.deps });
+    expect(c.aliases).toContain('opus[1m]');
+    expect(c.effortLevels).toEqual(['low', 'medium', 'high', 'xhigh', 'max']); // `auto` is a reset verb, not selectable
+    expect(c.models).toEqual(['claude-opus-5', 'claude-sonnet-5']);
+    expect(c.settingsEffortLevels).toEqual(['low', 'medium', 'high', 'xhigh']);
+    expect(c.availableModels).toEqual(['opus', 'haiku', 'sonnet']);
+    expect(c.sources).toEqual({ aliases: 'probe', models: 'binary', effortLevels: 'probe' });
+    expect(c.degraded).toBe(false);
+    expect(c.claudeVersion).toBe('2.1.277');
+    expect(t.runClaudeP).toHaveBeenCalledWith('/model', { model: 'haiku', timeoutMs: 45000 });
+    expect(t.runClaudeP).toHaveBeenCalledWith('/effort', { model: 'haiku', timeoutMs: 45000 });
+    expect(t.writeJson).toHaveBeenCalledWith(CACHE, c);
+  });
+  it('availableModels is null when no scope defines it', async () => {
+    const c = await resolveModelCatalog({ cwd: '/p', force: true, deps: mk().deps });
+    expect(c.availableModels).toBeNull();
+  });
+  it('fresh matching cache is returned without spawning; force bypasses it', async () => {
+    const t = mk({ files: { [CACHE]: cacheEntry() } });
+    const c = await resolveModelCatalog({ deps: t.deps });
+    expect(c.aliases).toEqual(['sonnet']);
+    expect(c.sources.aliases).toBe('cache');
+    expect(t.runClaudeP).not.toHaveBeenCalled();
+    await resolveModelCatalog({ force: true, deps: t.deps });
+    expect(t.runClaudeP).toHaveBeenCalledTimes(2);
+  });
+  it('probe timeout falls back to stale cache and marks degraded', async () => {
+    const t = mk({ files: { [CACHE]: cacheEntry({ probedAt: new Date(NOW - 48 * 3600e3).toISOString() }) }, deps: { runClaudeP: vi.fn(async () => ({ ok: false, error: 'timeout' })) } });
+    const c = await resolveModelCatalog({ deps: t.deps });
+    expect(c.aliases).toEqual(['sonnet']);
+    expect(c.effortLevels).toEqual(['low']);
+    expect(c.sources.aliases).toBe('cache');
+    expect(c.sources.effortLevels).toBe('cache');
+    expect(c.sources.models).toBe('binary');
+    expect(c.degraded).toBe(true);
+    expect(t.writeJson).not.toHaveBeenCalled();
+  });
+  it('stale cache from a different CLI version is used before the floor; no cache → floor', async () => {
+    const fail = { runClaudeP: vi.fn(async () => ({ ok: false })), scanModelIds: () => { throw new Error('ENOENT'); } };
+    const stale = mk({ files: { [CACHE]: cacheEntry({ claudeVersion: '1.0.0' }) }, deps: fail });
+    const c1 = await resolveModelCatalog({ deps: stale.deps });
+    expect(c1.aliases).toEqual(['sonnet']);
+    expect(c1.models).toEqual(['claude-old-1']);
+    const none = mk({ deps: fail });
+    const c2 = await resolveModelCatalog({ deps: none.deps });
+    expect(c2.aliases).toEqual(CATALOG_FLOOR.aliases);
+    expect(c2.effortLevels).toEqual(CATALOG_FLOOR.effortLevels);
+    expect(c2.models).toEqual([]);
+    expect(c2.sources).toEqual({ aliases: 'floor', models: 'floor', effortLevels: 'floor' });
+    expect(c2.degraded).toBe(true);
+  });
+  it('corrupt cache degrades to floor without throwing', async () => {
+    const t = mk({ files: { [CACHE]: '{not json' }, deps: { runClaudeP: vi.fn(async () => ({ ok: false })) } });
+    const c = await resolveModelCatalog({ deps: t.deps });
+    expect(c.aliases).toEqual(CATALOG_FLOOR.aliases);
+  });
+  it('single-flight collapses concurrent calls into one probe pair', async () => {
+    const t = mk();
+    const [a, b] = await Promise.all([resolveModelCatalog({ force: true, deps: t.deps }), resolveModelCatalog({ force: true, deps: t.deps })]);
+    expect(a).toBe(b);
+    expect(t.runClaudeP).toHaveBeenCalledTimes(2);
+  });
+  it('SM_E2E=1 never spawns: floor, or a cache when present', async () => {
+    const t = mk({ deps: { env: { SM_E2E: '1' } } });
+    const c = await resolveModelCatalog({ force: true, deps: t.deps });
+    expect(c.aliases).toEqual(CATALOG_FLOOR.aliases);
+    expect(t.runClaudeP).not.toHaveBeenCalled();
+    const t2 = mk({ files: { [CACHE]: cacheEntry() }, deps: { env: { SM_E2E: '1' } } });
+    expect((await resolveModelCatalog({ deps: t2.deps })).aliases).toEqual(['sonnet']);
+    expect(t2.runClaudeP).not.toHaveBeenCalled();
+  });
+});
+
+describe('catalog cache file (real write boundary)', () => {
+  it('is written under ~/.claude, a path the real validateWrite accepts', async () => {
+    const os = require('node:os'); const pth = require('node:path');
+    const config = require('../../config.cjs');
+    const realHome = os.homedir();
+    const file = pth.join(realHome, '.claude', 'session-manager', 'model-catalog.json');
+    const t = mk({ deps: { homeDir: () => realHome, writeJson: undefined } });
+    const written = [];
+    t.deps.writeJson = async (f, d) => { written.push(f); config.validateWrite(f); };
+    await resolveModelCatalog({ force: true, deps: t.deps });
+    expect(written).toEqual([file]);
+  });
+  it('a userData path is rejected by validateWrite (why the cache must not live there)', () => {
+    const config = require('../../config.cjs');
+    expect(() => config.validateWrite('/somewhere/userData/model-catalog.json')).toThrow(/outside allowed write boundaries/);
+  });
+});
+
+describe('binary scan guard', () => {
+  it('never scans a small shell-script stub; degrades to the floor', async () => {
+    const scan = vi.fn(() => ['claude-x-1']);
+    const t = mk({ fs: { statSync: () => ({ isFile: () => true, size: 300 }) }, deps: { scanModelIds: scan } });
+    const c = await resolveModelCatalog({ force: true, deps: t.deps });
+    expect(scan).not.toHaveBeenCalled();
+    expect(c.sources.models).toBe('floor');
+    expect(c.degraded).toBe(true);
+  });
+  it('never scans a large file that is a shell script', async () => {
+    const scan = vi.fn(() => ['claude-x-1']);
+    const t = mk({ fs: { readSync: (fd, buf) => { buf.write('#!/bin/bash\n'); return 12; } }, deps: { scanModelIds: scan } });
+    await resolveModelCatalog({ force: true, deps: t.deps });
+    expect(scan).not.toHaveBeenCalled();
+  });
+});
+
+describe('null CLI version key', () => {
+  it('neither serves a cache as fresh nor writes one', async () => {
+    const t = mk({ files: { [CACHE]: cacheEntry({ claudeVersion: null }) }, deps: { probeClaudeVersion: async () => null } });
+    const c = await resolveModelCatalog({ deps: t.deps });
+    expect(t.runClaudeP).toHaveBeenCalled();
+    expect(c.claudeVersion).toBeNull();
+    expect(t.writeJson).not.toHaveBeenCalled();
+  });
+  it('a null-version cache entry is never a fresh hit for a real version', async () => {
+    const t = mk({ files: { [CACHE]: cacheEntry({ claudeVersion: null }) } });
+    await resolveModelCatalog({ deps: t.deps });
+    expect(t.runClaudeP).toHaveBeenCalled();
+  });
+});
+
+describe('effort auto is never a flag value', () => {
+  it('drops `auto` from live and cached effort levels', async () => {
+    const t = mk({ files: { [CACHE]: cacheEntry({ effortLevels: ['low', 'auto'], probedAt: new Date(NOW - 48 * 3600e3).toISOString() }) }, deps: { runClaudeP: vi.fn(async () => ({ ok: false })) } });
+    const c = await resolveModelCatalog({ deps: t.deps });
+    expect(c.effortLevels).toEqual(['low']);
+  });
+  it('effortArgs and resolveEpicEffort never emit --effort auto', () => {
+    const { effortArgs } = require('../agentEffortResolve.cjs');
+    expect(effortArgs('auto')).toEqual([]);
+    expect(effortArgs('AUTO')).toEqual([]);
+    expect(effortArgs('inherit')).toEqual([]);
+    expect(effortArgs('high')).toEqual(['--effort', 'high']);
+  });
+});

package/src/main/lib/agentEffortResolve.cjs

@@ -0,0 +1,74 @@
+'use strict';
+
+/**
+ * agentEffortResolve.cjs — the effort twin of agentModelResolve.cjs: resolves
+ * the `--effort <level>` an Epic-/PRD-backed `claude` launch should carry,
+ * from the agentType persona's own `effort:` frontmatter field (written by
+ * agentLibrary.cjs's serializePersona; the key is literally `effort`).
+ *
+ * PRECEDENCE (explicit):
+ *   0. Epic-level `effort` (the New Session card's override, stored on the Epic
+ *      record; source 'epic') beats everything below. Only reachable on the
+ *      Chat/Terminal path (claudeSessionId) — a scheduled PRD has no Epic record
+ *      of its own to carry it. `inherit`/`auto` there means "no override".
+ *   1. persona `effort:` — project overlay (`<cwd>/.claude/agents/<name>.md`)
+ *      beats the global `~/.claude/agents/<name>.md` (same path resolver and
+ *      same reader as the model path: agentModelResolve.cjs's
+ *      readOverlayAwarePersona, i.e. personaMerge.cjs's field-level merge — a
+ *      frontmatter-only overlay can pin just `effort`; source is
+ *      'persona-overlay' only when the overlay itself supplied the value).
+ *   2. `inherit`, absent, dangling agentType, unreadable persona → `effort:
+ *      null`, meaning "pass NO --effort flag at all" so the CLI applies its
+ *      own settings.json / default resolution.
+ *
+ * This module NEVER reads settings.json and NEVER invents a fallback level.
+ * A caller must append the flag only when `effort` is a non-null string —
+ * never `--effort inherit`, `--effort null`, or an empty value.
+ *
+ * The persona value is passed through UNCHANGED (only trimmed): the CLI
+ * accepts low/medium/high/xhigh/max and, for an unknown level, merely warns
+ * (`Unknown --effort value 'x' — ignoring it and using the default effort.`)
+ * and proceeds at the default — so a wrong value degrades gracefully instead
+ * of failing the run, and rewriting it here would hide the mistake.
+ *
+ * Plain sync Node module, never throws (same contract as resolveEpicModel).
+ */
+
+const { findEpicByClaudeSessionId, epicOverrideValue, readOverlayAwarePersona } = require('./agentModelResolve.cjs');
+
+// `auto` is a `/effort` RESET verb, not a `--effort` value; it must never reach argv.
+const NON_FLAG_EFFORT = new Set(['inherit', 'auto']);
+
+const NO_EFFORT = Object.freeze({ effort: null, source: null });
+
+/**
+ * @param {{ cwd: string, claudeSessionId?: string, agentType?: string|null, deps?: object }} opts
+ *   `agentType` wins when given (scheduler PRD path); otherwise it is joined
+ *   from the Epic's `claudeSessionId` (Chat/Terminal path).
+ * @returns {{ effort: string|null, source: 'epic'|'persona'|'persona-overlay'|'inherit'|null }}
+ *   source null = no agentType/persona resolved; 'inherit' = persona present
+ *   but sets no level.
+ */
+function resolveEpicEffort({ cwd, claudeSessionId, agentType, deps = {} } = {}) {
+  try {
+    const epic = claudeSessionId ? findEpicByClaudeSessionId(cwd, claudeSessionId, deps) : null;
+    const override = epicOverrideValue(epic, 'effort');
+    if (override && !NON_FLAG_EFFORT.has(override.toLowerCase())) return { effort: override, source: 'epic' };
+    const type = agentType || epic?.agentType || null;
+    if (!type) return { ...NO_EFFORT };
+    const persona = readOverlayAwarePersona(type, { ...deps, cwd });
+    if (!persona) return { ...NO_EFFORT };
+    const raw = typeof persona.fm.effort === 'string' ? persona.fm.effort.trim() : '';
+    if (!raw || NON_FLAG_EFFORT.has(raw.toLowerCase())) return { effort: null, source: 'inherit' };
+    return { effort: raw, source: persona.provenance.effort === 'overlay' ? 'persona-overlay' : 'persona' };
+  } catch {
+    return { ...NO_EFFORT };
+  }
+}
+
+/** argv fragment for a resolved effort: `['--effort', level]` or `[]`. One place decides the "no flag" rule. */
+function effortArgs(effort) {
+  return typeof effort === 'string' && effort && !NON_FLAG_EFFORT.has(effort.toLowerCase()) ? ['--effort', effort] : [];
+}
+
+module.exports = { resolveEpicEffort, effortArgs };

package/src/main/lib/agentModelResolve.cjs

@@ -17,17 +17,21 @@
  * views literally call the same function instead of two functions that are
  * merely supposed to agree.
  *
+ * PRECEDENCE (explicit): Epic-level `model` (the New Session card's override,
+ * stored on the Epic record) > persona frontmatter `model` > `fallbackModel`.
+ * An Epic with no `model` key (every Epic minted before the override existed)
+ * resolves exactly as it always did.
+ *
  * Plain Node module (sync fs) — no Electron deps, mirrors epicMint.cjs's
  * readActiveIndex so this can be called from chatRunner.cjs's synchronous
  * executeRun() without restructuring it into an async flow.
  */
 
-const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
 const { splitFrontmatter } = require('./prdFrontmatter.cjs');
 const { readActiveIndex, resolvePersonaPaths } = require('./epicMint.cjs');
-const { PERSONA_NAME_RE } = require('../agentLibrary.cjs');
+const { resolveMergedPersona, PERSONA_NAME_RE } = require('./personaMerge.cjs');
 const configMgr = require('../config.cjs');
 
 /** The hardcoded floor every branch of resolveEpicModel falls back to — --model must never be omitted (CLAUDE.md "Automation model pinning"). */
@@ -56,7 +60,7 @@ function logDanglingPersonaOnce(cwd, agentType) {
       cwd,
       scope: 'agentModelResolve',
       level: 'warn',
-      message: `agentType '${agentType}' has no resolvable persona file — model resolution fell back to '${FALLBACK_MODEL}'`,
+      message: `agentType '${agentType}' has no resolvable persona file — model resolution fell back to '${FALLBACK_MODEL}' (and no persona effort applies)`,
       meta: { agentType },
     });
   } catch { /* logging must never break model resolution */ }
@@ -68,74 +72,55 @@ function logDanglingPersonaOnce(cwd, agentType) {
  * resolveSourcePromptIdFromClaudeSession uses (Epic:claude-session is 1:1).
  * Returns null if no matching Epic is found or it has no agentType set.
  */
-function findAgentTypeByClaudeSessionId(cwd, claudeSessionId, deps = {}) {
+function findEpicByClaudeSessionId(cwd, claudeSessionId, deps = {}) {
   if (!cwd || !claudeSessionId) return null;
   const load = deps.readActiveIndex || readActiveIndex;
   const { sessions } = load(cwd);
   for (const session of Object.values(sessions)) {
-    if (session && session.claudeSessionId === claudeSessionId) return session.agentType || null;
+    if (session && session.claudeSessionId === claudeSessionId) return session;
   }
   return null;
 }
 
-/**
- * Shared miss-tolerant reader `readOverlayAwarePersonaModel` below is a thin
- * wrapper over: tries each candidate path in order (`validatePath` then sync
- * `readFileSync`), and returns the first readable file's `model` frontmatter
- * field — even if that field is absent, which is why an empty-`model`
- * overlay file does NOT fall through to a later candidate (matches
- * `getPersonaBody`'s own semantics). Logs the dangling-persona warning at
- * most once per `(deps.cwd, agentType)` only when EVERY candidate misses.
- * Never throws.
- */
-function readModelFromCandidatePaths(candidates, agentType, deps) {
-  const validatePath = deps.validatePath || configMgr.validatePath;
-  for (const candidate of candidates) {
-    let real;
-    try {
-      real = validatePath(candidate);
-    } catch {
-      continue;
-    }
-    try {
-      const text = fs.readFileSync(real, 'utf8');
-      const { fm } = splitFrontmatter(text);
-      return fm.model || null;
-    } catch {
-      continue;
-    }
-  }
-  logDanglingPersonaOnce(deps.cwd, agentType);
-  return null;
+function findAgentTypeByClaudeSessionId(cwd, claudeSessionId, deps = {}) {
+  return findEpicByClaudeSessionId(cwd, claudeSessionId, deps)?.agentType || null;
+}
+
+/** A non-empty trimmed string from an Epic's optional `model`/`effort` override field, else null. */
+function epicOverrideValue(epic, field) {
+  const raw = epic && typeof epic[field] === 'string' ? epic[field].trim() : '';
+  return raw || null;
 }
 
 /**
- * Reads an Epic's agentType persona's `model` frontmatter field with the SAME
- * project-overlay-then-global precedence `agentLibrary.cjs`'s `getPersonaBody`
- * (and, through it, `resolvePrdPersonaForSpawn` below) already applies for a
- * scheduled PRD — `epicMint.cjs`'s `resolvePersonaPaths` is the shared path
- * resolver both readers go through, so there is exactly one place that decides
- * which of the two files wins.
+ * Reads an Epic's agentType persona through personaMerge.cjs's
+ * `resolveMergedPersona` — the ONE overlay-over-global merge every reader
+ * shares (overlay frontmatter keys win, absent keys and an empty overlay body
+ * fall back to the global; see that module's header for the `inherit` and
+ * malformed-overlay rules). Returns `{ fm, body, path, fromOverlay,
+ * provenance, ... }`, or null on a total miss / invalid name — never throws,
+ * and logs the dangling-persona warning at most once per (cwd, agentType).
  *
- * Sync (not `getPersonaBody`'s async `fsp.readFile`) because `resolveEpicModel`
- * must stay synchronous: `chatRunner.cjs`'s `executeRun()` registers its
- * cancel handle into `inFlight` synchronously, and its caller (`pump()`) reads
- * that entry back immediately after invoking the executor — an `await`
- * inserted ahead of that registration would run it a tick late and silently
- * break `cancel()`. Returns null on a total miss (neither location resolves)
- * — never throws.
+ * Sync (not `getPersonaBody`'s async form) because `resolveEpicModel` must
+ * stay synchronous: `chatRunner.cjs`'s `executeRun()` registers its cancel
+ * handle into `inFlight` synchronously, and its caller (`pump()`) reads that
+ * entry back immediately after invoking the executor — an `await` inserted
+ * ahead of that registration would run it a tick late and silently break
+ * `cancel()`. The PERSONA_NAME_RE traversal guard lives in the merge module.
  */
+function readOverlayAwarePersona(agentType, deps = {}) {
+  const persona = resolveMergedPersona(deps.cwd, agentType, deps);
+  if (!persona) {
+    if (agentType && PERSONA_NAME_RE.test(agentType)) logDanglingPersonaOnce(deps.cwd, agentType);
+    return null;
+  }
+  return persona;
+}
+
+/** The persona's `model` frontmatter field (overlay-then-global), or null. Never throws. */
 function readOverlayAwarePersonaModel(agentType, deps = {}) {
-  // Same guard agentLibrary.cjs's getPersonaBody applies before it joins
-  // `name` into a path: without it, a caller-supplied agentType 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 on this --model spawn path.
-  if (!agentType || !PERSONA_NAME_RE.test(agentType)) return null;
-  const resolvePaths = deps.resolvePersonaPaths || resolvePersonaPaths;
-  const { projectPath, globalPath } = resolvePaths(deps.cwd, agentType, deps);
-  return readModelFromCandidatePaths([projectPath, globalPath], agentType, deps);
+  const persona = readOverlayAwarePersona(agentType, deps);
+  return (persona && persona.fm.model) || null;
 }
 
 /**
@@ -179,7 +164,10 @@ function isProjectOverlayPersonaPath(cwd, agentType, personaPath, deps = {}) {
  */
 function resolveEpicModel({ cwd, claudeSessionId, fallbackModel = FALLBACK_MODEL, deps = {} } = {}) {
   try {
-    const agentType = findAgentTypeByClaudeSessionId(cwd, claudeSessionId, deps);
+    const epic = findEpicByClaudeSessionId(cwd, claudeSessionId, deps);
+    const override = epicOverrideValue(epic, 'model');
+    if (override && override !== 'inherit') return override;
+    const agentType = epic?.agentType || null;
     if (!agentType) return fallbackModel;
     const model = readOverlayAwarePersonaModel(agentType, { ...deps, cwd });
     if (!model || model === 'inherit') return fallbackModel;
@@ -237,7 +225,9 @@ async function resolvePrdPersonaForSpawn({ cwd, agentType, fallbackModel = FALLB
       reportOnce(cwd, agentType, deps);
       return miss;
     }
-    const { fm, body } = splitFrontmatter(persona.text);
+    // getPersonaBody returns the MERGED persona (fm + body); a bare `{ path, text }`
+    // (older injected reader) is parsed here.
+    const { fm, body } = persona.fm ? persona : splitFrontmatter(persona.text);
     const model = fm.model && fm.model !== 'inherit' ? fm.model : fallbackModel;
     const systemPrompt = buildPersonaBodyText(body, persona.path);
     return { model, systemPrompt, personaPath: persona.path };
@@ -250,7 +240,10 @@ module.exports = {
   FALLBACK_MODEL,
   resolveEpicModel,
   findAgentTypeByClaudeSessionId,
+  findEpicByClaudeSessionId,
+  epicOverrideValue,
   readOverlayAwarePersonaModel,
+  readOverlayAwarePersona,
   isProjectOverlayPersonaPath,
   resolvePrdPersonaForSpawn,
 };

package/src/main/lib/agentPersonaSchema.cjs

@@ -1,3 +1,4 @@
+// @ts-check
 /**
  * Canonical runtime schema for an Agent persona WRITE payload, mirroring the
  * TS `AgentPersonaSaveInput` interface in src/preload/api.d.ts
@@ -50,12 +51,15 @@ const AgentPersonaSaveSchema = z.object({
   description: BoundedString,
   tools: z.array(BoundedString),
   model: BoundedString,
+  effort: BoundedString.optional(),
   color: BoundedString,
   tags: z.array(WorkTypeSchema),
   projects: z.array(ProjectEntrySchema).optional(),
   action: z.string().max(20000).optional(),
   actionLabel: BoundedString.optional(),
   title: BoundedString.optional(),
+  // Set = write this project's frontmatter-only override (model/effort only) instead of the global file.
+  projectName: BoundedString.optional(),
   // Unbounded — a persona's body is arbitrary system-prompt prose.
   body: z.string(),
 });
@@ -64,6 +68,7 @@ const AgentPersonaSaveSchema = z.object({
  * Throws a clear, descriptive error (not a raw ZodError dump) when `persona`
  * doesn't match AgentPersonaSaveSchema. Mirrors assertValidPromptSession /
  * assertValidScheduleJob's shape and message format exactly.
+ * @param {unknown} persona
  */
 function assertValidAgentPersonaSave(persona) {
   const result = AgentPersonaSaveSchema.safeParse(persona);