claude-code-session-manager 0.92.0 → 0.93.0

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

@@ -18,7 +18,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
 const { encodeCwd } = require('../encodeCwd.cjs');
-const { resolveEffectiveModelInfo, isConcreteModelId, computeEffortReachable } = require('../effectiveModelInfo.cjs');
+const { resolveEffectiveModelInfo, isConcreteModelId, computeEffortEnvReachable } = require('../effectiveModelInfo.cjs');
 // config.cjs's `allowedRoots` is a module-level singleton seeded from
 // os.homedir() at FIRST require — since this test's HOME changes every test
 // (fresh mkdtemp), a persona lookup (getPersonaBody -> validatePath) would
@@ -223,17 +223,22 @@ test('isConcreteModelId treats known CLI aliases as non-concrete and everything
   expect(isConcreteModelId('opus')).toBe(false);
   expect(isConcreteModelId('sonnet')).toBe(false);
   expect(isConcreteModelId('haiku')).toBe(false);
+  expect(isConcreteModelId('opus[1m]')).toBe(false);
+  expect(isConcreteModelId('best')).toBe(false);
+  expect(isConcreteModelId('opusplan')).toBe(false);
+  expect(isConcreteModelId('default')).toBe(false);
+  expect(isConcreteModelId('claude-opus-4-7[1m]')).toBe(true);
   expect(isConcreteModelId('fable')).toBe(false);
   expect(isConcreteModelId(null)).toBe(false);
   expect(isConcreteModelId('claude-opus-5')).toBe(true);
 });
 
-test('effortReachable is always false for an app-launched session — cleanChildEnv strips CLAUDE_EFFORT and CLAUDE_CODE_* before a child ever sees them', () => {
-  expect(computeEffortReachable({})).toBe(false);
+test('effortEnvReachable is always false for an app-launched session — cleanChildEnv strips CLAUDE_EFFORT and CLAUDE_CODE_* before a child ever sees them', () => {
+  expect(computeEffortEnvReachable({})).toBe(false);
 });
 
-test('resolveEffectiveModelInfo surfaces effortReachable alongside the model fields', async () => {
+test('resolveEffectiveModelInfo surfaces effortEnvReachable alongside the model fields', async () => {
   writeGlobalPersona('any', ['model: sonnet']);
   const info = await resolveEffectiveModelInfo({ cwd, agentType: 'any' });
-  expect(info.effortReachable).toBe(false);
+  expect(info.effortEnvReachable).toBe(false);
 });

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

@@ -50,12 +50,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(),
 });

package/src/main/lib/effectiveModelInfo.cjs

@@ -13,11 +13,11 @@
  * "we don't know; the CLI resolves this alias at launch." The two must
  * never collapse into one optimistic string.
  *
- * Effort-level resolution is deliberately NOT here — it already exists,
- * unused, in the renderer's `useEffectiveSettings.ts` (a scope-chain reader
- * with a file watcher). This module supplies only the half that genuinely
- * needs main-process filesystem access: persona lookup (overlay-aware) and
- * concrete-model evidence (scheduler run logs, session transcripts).
+ * PERSONA effort IS here now (agentEffortResolve.cjs): it needs the same
+ * main-process, overlay-aware persona read as the persona model, and a launch
+ * now actually passes it as `--effort`. The settings.json effortLevel
+ * scope-chain read stays in the renderer (`useEffectiveSettings.ts`) as the
+ * FALLBACK when the persona sets no level — this module never reads settings.
  *
  * Never throws — every lookup failure degrades a field to null, same
  * contract as agentModelResolve.cjs's resolveEpicModel.
@@ -29,12 +29,17 @@ const os = require('node:os');
 const { splitFrontmatter } = require('./prdFrontmatter.cjs');
 const { resolveEpicTranscriptPath } = require('./epicTranscriptPath.cjs');
 
-// Mirrors rawSessionModel.ts's RAW_MODELS — duplicated rather than imported
+// Deliberately stays a FIXED alias set (reviewed against the catalog-driven raw picker): it answers
+// "alias vs concrete id", not "which options to offer", so live catalog ids must not enter it.
+// Mirrors rawSessionModel.ts's RAW_MODELS fallback — duplicated rather than imported
 // because that file is a renderer ES module and this is a main-process CJS
 // module (CLAUDE.md: "No CommonJS in renderer, no ES modules in main").
 // Anything NOT in this set is treated as an already-concrete pinned model id
 // (e.g. 'claude-opus-5'), never as an alias needing evidence.
-const KNOWN_MODEL_ALIASES = new Set(['opus', 'sonnet', 'haiku', 'fable']);
+// Also the non-family CLI aliases the Agent Library picker can now write
+// (best / opusplan / default); a trailing `[1m]`-style suffix is stripped
+// before the lookup (see isConcreteModelId), so 'opus[1m]' is an alias too.
+const KNOWN_MODEL_ALIASES = new Set(['opus', 'sonnet', 'haiku', 'fable', 'best', 'opusplan', 'default']);
 
 // Run-log evidence (scheduler.cjs's executeJob, ~line 4473) is written
 // essentially at dispatch time, before any of the run's own stdout streams
@@ -54,10 +59,14 @@ function runsDir(homeDir) {
 }
 
 function isConcreteModelId(modelAlias) {
-  return Boolean(modelAlias) && !KNOWN_MODEL_ALIASES.has(modelAlias);
+  if (!modelAlias) return false;
+  // 'opus[1m]' is an alias with a context suffix; 'claude-opus-4-7[1m]' keeps its id.
+  return !KNOWN_MODEL_ALIASES.has(modelAlias.replace(/\[[^\]]*\]$/, ''));
 }
 
 /**
+ * ENV-VAR question only (`effortEnvReachable`): persona effort now travels on argv as `--effort`,
+ * which cleanChildEnv cannot strip — so this says nothing about whether effort reaches the CLI.
  * True when this app's spawn path (cleanEnv.cjs's cleanChildEnv) would strip
  * an effort env var before a child ever saw it — i.e. whether the settings
  * schema's env-var effort configuration path is actually reachable for an
@@ -65,7 +74,7 @@ function isConcreteModelId(modelAlias) {
  * hardcoding a boolean, so this self-corrects if that deletion list ever
  * changes instead of silently drifting stale.
  */
-function computeEffortReachable(deps) {
+function computeEffortEnvReachable(deps) {
   try {
     const { cleanChildEnv } = deps.cleanEnv || require('./cleanEnv.cjs');
     const probe = cleanChildEnv({ CLAUDE_EFFORT: 'high', CLAUDE_CODE_EFFORT_LEVEL: 'high' });
@@ -106,15 +115,18 @@ async function resolvePersonaModelAlias(cwd, agentType, deps) {
   } catch {
     persona = null;
   }
-  if (!persona) return { modelAlias: null, modelSource: 'fallback' };
+  if (!persona) return { modelAlias: null, modelSource: 'fallback', provenance: {} };
 
-  const { fm } = splitFrontmatter(persona.text);
-  const fromOverlay = isProjectOverlayPersonaPath(cwd, agentType, persona.path, deps);
+  // getPersonaBody returns the MERGED persona with per-field provenance; a bare
+  // `{ path, text }` (older injected reader) falls back to whole-file provenance.
+  const fm = persona.fm || splitFrontmatter(persona.text).fm;
+  const provenance = persona.provenance
+    || Object.fromEntries(Object.keys(fm).map((k) => [k, isProjectOverlayPersonaPath(cwd, agentType, persona.path, deps) ? 'overlay' : 'global']));
 
   if (fm.model && fm.model !== 'inherit') {
-    return { modelAlias: fm.model, modelSource: fromOverlay ? 'persona-overlay' : 'persona' };
+    return { modelAlias: fm.model, modelSource: provenance.model === 'overlay' ? 'persona-overlay' : 'persona', provenance };
   }
-  return { modelAlias: null, modelSource: 'inherit' };
+  return { modelAlias: null, modelSource: 'inherit', provenance };
 }
 
 /** Best-effort read of `<cwd>/session-manager-operations/scheduler/state/queue.json`'s hot jobs[]. */
@@ -268,21 +280,25 @@ function findLatestTranscriptModel(cwd, agentType, deps) {
 
 /**
  * resolveEffectiveModelInfo({ cwd, agentType, deps? }) →
- *   { agentType, modelAlias, modelSource, resolvedModelId, resolvedFrom, effortReachable }
+ *   { agentType, modelAlias, modelSource, resolvedModelId, resolvedFrom, effortEnvReachable,
+ *     personaEffort, personaEffortSource }
  *
  * Never throws. `cwd` is normalized through the same worktree/ops-internal
  * -aware resolver every ops-root reader goes through, so a job worktree cwd
  * resolves to its main project tree before anything is looked up.
  */
 async function resolveEffectiveModelInfo({ cwd, agentType, deps = {} } = {}) {
-  const effortReachable = computeEffortReachable(deps);
+  const effortEnvReachable = computeEffortEnvReachable(deps);
   const miss = {
     agentType: agentType || null,
     modelAlias: null,
     modelSource: 'fallback',
+    personaProvenance: {},
     resolvedModelId: null,
     resolvedFrom: null,
-    effortReachable,
+    effortEnvReachable,
+    personaEffort: null,
+    personaEffortSource: null,
   };
   if (!cwd || !agentType) return miss;
 
@@ -291,8 +307,10 @@ async function resolveEffectiveModelInfo({ cwd, agentType, deps = {} } = {}) {
     const normalizedCwd = projectRootOf(path.resolve(cwd));
     if (!normalizedCwd) return miss;
 
-    const { modelAlias, modelSource } = await resolvePersonaModelAlias(normalizedCwd, agentType, deps);
-    const result = { agentType, modelAlias, modelSource, resolvedModelId: null, resolvedFrom: null, effortReachable };
+    const { modelAlias, modelSource, provenance: personaProvenance } = await resolvePersonaModelAlias(normalizedCwd, agentType, deps);
+    const { effort: personaEffort, source: personaEffortSource } = (deps.agentEffortResolve || require('./agentEffortResolve.cjs'))
+      .resolveEpicEffort({ cwd: normalizedCwd, agentType, deps });
+    const result = { agentType, modelAlias, modelSource, personaProvenance, resolvedModelId: null, resolvedFrom: null, effortEnvReachable, personaEffort, personaEffortSource };
 
     if (isConcreteModelId(modelAlias)) {
       // Already a concrete pinned id — echo it back, fabricate no evidence.
@@ -327,6 +345,6 @@ async function resolveEffectiveModelInfo({ cwd, agentType, deps = {} } = {}) {
 module.exports = {
   resolveEffectiveModelInfo,
   isConcreteModelId,
-  computeEffortReachable,
+  computeEffortEnvReachable,
   KNOWN_MODEL_ALIASES,
 };