claude-code-session-manager 0.86.0 → 0.88.0

package/{scripts → src/main}/lib/activeSessions.cjs

@@ -11,7 +11,9 @@
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
-const { KIND_CONFIG: WORKTREE_KIND_CONFIG } = require('../../src/main/lib/gitWorktree.cjs');
+const { KIND_CONFIG: WORKTREE_KIND_CONFIG } = require('./gitWorktree.cjs');
+const { OPS_ROOT_DIR } = require('./opsOwnership.cjs');
+const { classifyCwd, worktreeMainRootOf } = require('./cwdClassify.cjs');
 
 const HOME = os.homedir();
 const TMPDIR = os.tmpdir();
@@ -31,7 +33,7 @@ const TMPDIR = os.tmpdir();
 //     could not — e.g. a bare, .git-less worktree-root directory.
 const TMP_DROP_ROOTS = {
   exactDropCwds: [TMPDIR],
-  prefixDropRoots: [WORKTREE_KIND_CONFIG.job.root, WORKTREE_KIND_CONFIG.epic.root],
+  get prefixDropRoots() { return [WORKTREE_KIND_CONFIG.job.root, WORKTREE_KIND_CONFIG.epic.root]; },
 };
 
 // Transcript reads only need the last line with a `cwd` field — a few dozen
@@ -41,6 +43,30 @@ const TAIL_BYTES = 64 * 1024;
 // Safety cap on distinct cwds to bound result set size. O(1) extra space.
 const MAX_CWDS = 50;
 
+// activeProjectCwds' scan is a readdirSync of every dir under ~/.claude
+// /projects (2209 dirs / 8.8 GB observed) plus a statSync per transcript —
+// ~270 ms warm. reconcile() calls into it (directly or via allProjectCwds)
+// several times per pass, so cache the resolved cwd list keyed on the
+// resolved argument TUPLE (projectsDir, maxAgeMin, maxCwds) — never on
+// `!opts`, since allProjectCwds always constructs an options object and that
+// guard would cache nothing on the hottest path.
+//
+// Invalidation: projectsDir's own mtime (bumps when a project DIRECTORY is
+// added/removed — NOT when an existing transcript gains a line, which is
+// fine: a project already in the list stays in the list) plus a short TTL
+// as the backstop for everything else. Same mtime-keyed idiom as
+// scheduler/prdParser.cjs's dirCache and queueHistory.cjs's historyCacheKey.
+// TTL sits above the 60 s dispatch-loop interval (scheduler POLL_INTERVAL_MS) so
+// one pass never re-scans cold. Cached arrays are frozen — shared, never mutated.
+const CACHE_TTL_MS = 120_000;
+const EMPTY_CWDS = Object.freeze([]);
+const cwdScanCache = new Map(); // key -> { dirMtimeMs, cachedAt, result }
+
+/** Forces the next activeProjectCwds/allProjectCwds call to rescan. */
+function bustProjectCwdCache() {
+  cwdScanCache.clear();
+}
+
 // The ops-root folder name. A transcript's `cwd` can point INSIDE it whenever
 // an agent `cd`s into an artifact directory (a PRD folder, prompt-sessions,
 // scheduler/state) — Claude Code records the new absolute cwd on every
@@ -55,95 +81,18 @@ const MAX_CWDS = 50;
 // Truncating at the segment is strictly better than dropping the row: the
 // ancestor IS the project the agent was working in, so the active-project
 // signal survives instead of being silently lost.
-const OPS_DIRNAME = 'session-manager-operations';
-
-// Bound on the ancestor walk in worktreeMainRootOf — well past any real
-// filesystem depth, purely to guarantee termination without relying on
-// reaching '/' (e.g. a symlink loop or an unusually deep path).
-const MAX_WORKTREE_WALK = 40;
-
-const WORKTREES_MARKER = `${path.sep}.git${path.sep}worktrees${path.sep}`;
-
-/**
- * worktreeMainRootOf(cwd) → the main tree's root when cwd sits inside a
- * linked `git worktree` (job/epic worktrees under os.tmpdir(), or a
- * user-made one anywhere). Walks UP from cwd looking for a `.git` entry:
- *   - `.git` is a FILE (linked worktree) whose first line is
- *     `gitdir: <main>/.git/worktrees/<name>` → returns <main>.
- *   - `.git` is a DIRECTORY (already the main tree) → returns that ancestor.
- *   - nothing found within MAX_WORKTREE_WALK levels → returns null.
- * Pure fs, synchronous, never throws — any unexpected shape (garbled file,
- * unreadable entry, gitdir path without the worktrees marker) yields null so
- * the caller leaves the cwd unchanged rather than guessing.
- */
-function worktreeMainRootOf(cwd) {
-  let dir = cwd;
-  for (let i = 0; i < MAX_WORKTREE_WALK; i++) {
-    const gitPath = path.join(dir, '.git');
-    let stat;
-    try {
-      stat = fs.statSync(gitPath);
-    } catch {
-      stat = null;
-    }
-    if (stat) {
-      if (stat.isDirectory()) return dir;
-      if (stat.isFile()) {
-        let body;
-        try {
-          body = fs.readFileSync(gitPath, 'utf8');
-        } catch {
-          return null;
-        }
-        const firstLine = body.split('\n', 1)[0].trim();
-        const prefix = 'gitdir:';
-        if (!firstLine.startsWith(prefix)) return null;
-        const gitdir = firstLine.slice(prefix.length).trim();
-        const markerIdx = gitdir.indexOf(WORKTREES_MARKER);
-        if (markerIdx <= 0) return null;
-        const candidateMain = gitdir.slice(0, markerIdx);
-        const worktreeName = gitdir.slice(markerIdx + WORKTREES_MARKER.length).split(path.sep)[0];
-        // Round-trip verification: gitdir's content is a plain file that
-        // anything on disk could have written (e.g. a nested `.git` file
-        // tracked inside an untrusted repo), so it must not be trusted to
-        // redirect callers to an arbitrary attacker-chosen absolute path.
-        // A genuine linked worktree's admin dir back-references the exact
-        // `.git` FILE we are resolving via its own `gitdir` pointer file —
-        // require that round trip before accepting candidateMain.
-        if (!worktreeName) return null;
-        const adminGitdirFile = path.join(candidateMain, '.git', 'worktrees', worktreeName, 'gitdir');
-        let backRef;
-        try {
-          backRef = fs.readFileSync(adminGitdirFile, 'utf8').trim();
-        } catch {
-          return null;
-        }
-        if (path.resolve(backRef) !== path.resolve(gitPath)) return null;
-        return candidateMain;
-      }
-      return null;
-    }
-    const parent = path.dirname(dir);
-    if (parent === dir) return null;
-    dir = parent;
-  }
-  return null;
-}
+const OPS_DIRNAME = OPS_ROOT_DIR;
 
 /**
  * projectRootOf(cwd) → the project root for a cwd that may sit inside an ops
  * tree and/or a linked git worktree. Returns cwd unchanged when neither
- * applies. Only the FIRST ops-dir occurrence matters — a nested stray ops
- * root is itself the bug, never a project. The ops-dir truncation runs
- * first, then the worktree resolution, so a cwd deep inside a worktree's OWN
- * ops tree still lands on the real project's main root.
+ * applies, or when the worktree cannot be proven (kind `unknown` — callers that
+ * WRITE must consult classifyCwd; this stays total so dispatch never breaks).
+ * The classification itself (outermost ops truncation, then worktree
+ * resolution) lives in cwdClassify.cjs.
  */
 function projectRootOf(cwd) {
-  const parts = cwd.split(path.sep);
-  const i = parts.indexOf(OPS_DIRNAME);
-  const truncated = i > 0 ? (parts.slice(0, i).join(path.sep) || path.sep) : cwd;
-  const mainRoot = worktreeMainRootOf(truncated);
-  return mainRoot || truncated;
+  return classifyCwd(cwd).projectRoot ?? cwd;
 }
 
 /**
@@ -190,6 +139,23 @@ function activeProjectCwds(maxAgeMin = 90, {
   maxCwds = MAX_CWDS,
   tmpDropRoots = TMP_DROP_ROOTS,
 } = {}) {
+  const cacheKey = [projectsDir, maxAgeMin, maxCwds].join('|');
+  let dirMtimeMs;
+  try {
+    dirMtimeMs = fs.statSync(projectsDir).mtimeMs;
+  } catch {
+    // Missing/unreadable dir: nothing to scan, and any prior cache entry for
+    // this key must not survive to be handed back once the dir later
+    // appears — drop it rather than caching this empty result.
+    cwdScanCache.delete(cacheKey);
+    return EMPTY_CWDS;
+  }
+  const cached = cwdScanCache.get(cacheKey);
+  const now0 = Date.now();
+  if (cached && cached.dirMtimeMs === dirMtimeMs && now0 - cached.cachedAt < CACHE_TTL_MS) {
+    return cached.result;
+  }
+
   // maxAgeMin === Infinity means "every project ever seen, no recency filter"
   // (allProjectCwds below). Date.now() - Infinity is -Infinity, which every
   // mtime clears — spelled out here because it reads like an accident.
@@ -202,14 +168,18 @@ function activeProjectCwds(maxAgeMin = 90, {
     // Normalize an ops-internal cwd up to its project root BEFORE any of the
     // checks below — the stray-ops-root incident (see OPS_DIRNAME above) got
     // through precisely because such a path is absolute and does exist.
-    const cwd = projectRootOf(rawCwd);
+    const classified = classifyCwd(rawCwd);
+    // `unknown` (a .git file we cannot resolve) is non-registrable: registering
+    // it would hand every consumer a project whose ops writes are refused.
+    if (classified.kind === 'unknown') return;
+    const cwd = classified.projectRoot;
     // Must be ABSOLUTE. A relative fragment would pass the statSync below
     // whenever it happens to resolve against THIS process's own cwd, and
     // every consumer (queueStore.projectStateDir, prdLocations) then joins
     // it into an ops-root path that lands somewhere arbitrary. Callers key
     // whole per-project state off these strings — a project is a cwd, and a
     // cwd is an absolute path.
-    if (!path.isAbsolute(cwd)) return;
+    if (!cwd || !path.isAbsolute(cwd)) return;
     // Drop-guard of last resort: a cwd that is (or sits inside) a known
     // worktree-scratch root after projectRootOf's normalization is one
     // worktreeMainRootOf could not resolve to a main tree — never a real
@@ -231,7 +201,7 @@ function activeProjectCwds(maxAgeMin = 90, {
 
   // Scan ~/.claude/projects/*/  transcript *.jsonl files.
   let slugs;
-  try { slugs = fs.readdirSync(projectsDir); } catch { return result; }
+  try { slugs = fs.readdirSync(projectsDir); } catch { cwdScanCache.delete(cacheKey); return Object.freeze(result); }
 
   for (const slug of slugs) {
     if (result.length >= maxCwds) break;
@@ -266,6 +236,8 @@ function activeProjectCwds(maxAgeMin = 90, {
     }
   }
 
+  Object.freeze(result);
+  cwdScanCache.set(cacheKey, { dirMtimeMs, cachedAt: now0, result });
   return result;
 }
 
@@ -288,4 +260,10 @@ function allProjectCwds(opts = {}) {
   return activeProjectCwds(Infinity, { maxCwds: 500, ...opts });
 }
 
-module.exports = { activeProjectCwds, allProjectCwds, projectRootOf, worktreeMainRootOf };
+module.exports = {
+  activeProjectCwds,
+  allProjectCwds,
+  projectRootOf,
+  worktreeMainRootOf,
+  bustProjectCwdCache,
+};

package/src/main/lib/adoptedRunSupervisor.cjs

@@ -0,0 +1,136 @@
+'use strict';
+
+/**
+ * adoptedRunSupervisor.cjs — re-arms the budget watchdog, idle-tail kill and
+ * deadman for an executor the boot SPARED (scheduler.cjs stamps
+ * `adoptedAtBoot`), from the durable `<slug>.supervisor.json` record.
+ *
+ * executeJob attaches those three timers to the child it spawned; an adopted
+ * executor belongs to a dead app process, so nothing supervised it (and a
+ * quietMachine row held no lease). Here the same three conditions are polled
+ * against the record's own numbers (budgetMs / startedAt, idleKillMs vs the
+ * log mtime, maxDurationMs) by the app process that owns the row. The
+ * signal goes to the recorded process group only after the pid is proven to
+ * still be the recorded process (procIdentity, fail-closed). It never mints
+ * a slot token: the adopted row stays `untrackedRunning` in pickNextBatch.
+ *
+ * Plain Node, no electron — every effect is injected so it is unit-testable
+ * with fake timers and without scheduler.cjs.
+ */
+
+/**
+ * evaluateAdoptedRun(record, { now, logMtimeMs, defaultMaxDurationMs })
+ *   → { kind: 'deadman'|'budget'|'idle-tail', reason } | null
+ * Pure. Precedence deadman > budget > idle-tail (hardest kill first).
+ */
+function evaluateAdoptedRun(record, { now, logMtimeMs, defaultMaxDurationMs = 0 }) {
+  const started = Number.isFinite(record.startedAt) ? record.startedAt : null;
+  const elapsed = started === null ? null : now - started;
+  const deadmanMs = record.maxDurationMs > 0 ? record.maxDurationMs : defaultMaxDurationMs;
+  if (elapsed !== null && deadmanMs > 0 && elapsed >= deadmanMs) {
+    return { kind: 'deadman', reason: `deadman: ran ${Math.round(elapsed / 60_000)}m (>= ${Math.round(deadmanMs / 60_000)}m)` };
+  }
+  if (elapsed !== null && record.budgetMs > 0 && elapsed >= record.budgetMs) {
+    return {
+      kind: 'budget',
+      reason: `wall-clock budget exceeded: ran ${Math.round(elapsed / 60_000)}m against a ${Math.round(record.budgetMs / 60_000)}m budget (adopted after app restart)`,
+    };
+  }
+  if (record.idleKillMs > 0 && Number.isFinite(logMtimeMs) && now - logMtimeMs > record.idleKillMs) {
+    return { kind: 'idle-tail', reason: `idle-output: log mtime stalled ${Math.round((now - logMtimeMs) / 1000)}s (> ${Math.round(record.idleKillMs / 1000)}s)` };
+  }
+  return null;
+}
+
+/**
+ * superviseAdoptedRun(record, deps) → { cancel(), check() }
+ * One poll timer per adopted run; `check()` runs once immediately so a run
+ * already past its budget at boot is killed without waiting a full interval.
+ * deps: { logPath, now, statLogMtimeMs, pidAlive, identityOf, isDifferentProcess,
+ *   killGroup(pid, signal), stampKill(kind, reason) → Promise, log(msg),
+ *   checkIntervalMs, sigkillAfterMs, defaultMaxDurationMs }
+ */
+function superviseAdoptedRun(record, deps) {
+  const {
+    logPath, now = Date.now, statLogMtimeMs, pidAlive, identityOf, isDifferentProcess, killGroup,
+    stampKill, log = () => {}, checkIntervalMs, sigkillAfterMs, defaultMaxDurationMs = 0,
+  } = deps;
+  let done = false;
+  let timer = null;
+  let killTimer = null;
+
+  const isOurs = () => pidAlive(record.pid) && !isDifferentProcess(record.identity, identityOf(record.pid));
+  const cancel = () => {
+    done = true;
+    if (timer) clearInterval(timer);
+  };
+
+  async function check() {
+    if (done) return null;
+    if (!isOurs()) { cancel(); return 'gone'; } // exited (reaper finalizes) or pid recycled — never signal
+    const verdict = evaluateAdoptedRun(record, {
+      now: now(), logMtimeMs: statLogMtimeMs(logPath), defaultMaxDurationMs,
+    });
+    if (!verdict) return null;
+    cancel();
+    try { await stampKill(verdict.kind, verdict.reason); } catch (e) { log(`stampKill failed: ${e?.message ?? e}`); }
+    if (!isOurs()) return 'gone'; // exited while the stamp was in flight
+    const first = verdict.kind === 'deadman' ? 'SIGKILL' : 'SIGTERM';
+    log(`adopted-run ${verdict.kind} watchdog: ${verdict.reason} — ${first} process group`);
+    killGroup(record.pgid || record.pid, first, record.pid);
+    if (first === 'SIGTERM') {
+      killTimer = setTimeout(() => {
+        if (isOurs()) killGroup(record.pgid || record.pid, 'SIGKILL', record.pid);
+      }, sigkillAfterMs);
+      if (killTimer.unref) killTimer.unref();
+    }
+    return verdict.kind;
+  }
+
+  timer = setInterval(() => { check().catch((e) => log(`check failed: ${e?.message ?? e}`)); }, checkIntervalMs);
+  if (timer.unref) timer.unref();
+  return {
+    cancel() { cancel(); if (killTimer) clearTimeout(killTimer); },
+    check,
+  };
+}
+
+/**
+ * superviseAdoptedRuns(jobs, ctx) → Promise<string[]> (slugs newly armed)
+ * Arms a supervisor for every `running` row stamped adoptedAtBoot that has
+ * none in `ctx.registry` (Map key `slug|runId`), drops registry entries whose
+ * row is no longer that run, re-acquires the quietMachine lease and stamps
+ * supervisedAt. ctx: { registry, runDir(row), readRecord(runDir, slug),
+ *   lease: { acquire, holder }, markSupervised(row), makeDeps(row, record) }
+ * Complexity: O(jobs).
+ */
+async function superviseAdoptedRuns(jobs, ctx) {
+  const { registry, runDir, readRecord, lease, markSupervised, makeDeps } = ctx;
+  const live = new Set();
+  const armed = [];
+  for (const j of jobs) {
+    if (j.status !== 'running' || !j.adoptedAtBoot) continue;
+    const key = `${j.slug}|${j.runId ?? ''}`;
+    live.add(key);
+    if (registry.has(key)) continue;
+    const dir = runDir(j);
+    const record = dir ? readRecord(dir, j.slug) : null;
+    if (!record || !record.pid) continue; // no durable record → nothing to re-arm from
+    if (j.quietMachine === true && !lease.acquire(j.slug) && lease.holder() !== j.slug) {
+      console.warn(`[scheduler] adopted quietMachine run ${j.slug}: lease held by ${lease.holder()} — not re-acquired`);
+    }
+    const handle = superviseAdoptedRun(record, makeDeps(j, record));
+    registry.set(key, handle);
+    armed.push(j.slug);
+    await markSupervised(j);
+    handle.check().catch(() => {});
+  }
+  for (const [key, handle] of registry) {
+    if (live.has(key)) continue;
+    handle.cancel();
+    registry.delete(key);
+  }
+  return armed;
+}
+
+module.exports = { evaluateAdoptedRun, superviseAdoptedRun, superviseAdoptedRuns };

package/src/main/lib/agentModelResolve.cjs

@@ -3,14 +3,19 @@
 /**
  * agentModelResolve.cjs — resolves the `--model` an Epic's session should
  * launch a headless `claude -p` (or Terminal `claude`) process with: its
- * agentType persona's own `model` field (Agent Library) when the Epic has
- * one set and it isn't 'inherit', else `fallbackModel`.
+ * agentType persona's own `model` field, project-overlay-then-global
+ * (`epicMint.cjs`'s `resolvePersonaPaths`), when the Epic has one set and
+ * it isn't 'inherit', else `fallbackModel`.
  *
  * Extracted from PRD agent-model-default-terminal (which wired this for the
  * Terminal-view launch in EpicTerminalPane.tsx) so chatRunner.cjs's headless
  * Chat-view launch resolves the SAME persona-derived model — Chat and
  * Terminal are two VIEWS over one Epic session (CLAUDE.md) and must agree on
- * which model that session launches with.
+ * which model that session launches with. Terminal reaches `resolveEpicModel`
+ * through the `agents:resolve-epic-model` IPC (main-process only; the
+ * renderer has no fs access) rather than a second implementation, so the two
+ * views literally call the same function instead of two functions that are
+ * merely supposed to agree.
  *
  * Plain Node module (sync fs) — no Electron deps, mirrors epicMint.cjs's
  * readActiveIndex so this can be called from chatRunner.cjs's synchronous
@@ -21,7 +26,8 @@ const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
 const { splitFrontmatter } = require('./prdFrontmatter.cjs');
-const { readActiveIndex } = require('./epicMint.cjs');
+const { readActiveIndex, resolvePersonaPaths } = require('./epicMint.cjs');
+const { PERSONA_NAME_RE } = require('../agentLibrary.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"). */
@@ -73,30 +79,87 @@ function findAgentTypeByClaudeSessionId(cwd, claudeSessionId, deps = {}) {
 }
 
 /**
- * Reads a global agent persona's `model` frontmatter field by name
- * (`~/.claude/agents/<agentType>.md`), sync. Returns null on any miss
- * (no such file, unreadable, no `model` key) — never throws.
+ * 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 readPersonaModel(agentType, deps = {}) {
-  if (!agentType) return null;
-  const globalDir = deps.globalDir || path.join(os.homedir(), '.claude', 'agents');
+function readModelFromCandidatePaths(candidates, agentType, deps) {
   const validatePath = deps.validatePath || configMgr.validatePath;
-  let real;
-  try {
-    real = validatePath(path.join(globalDir, `${agentType}.md`));
-  } catch {
-    logDanglingPersonaOnce(deps.cwd, agentType);
-    return null;
+  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;
+    }
   }
-  let text;
+  logDanglingPersonaOnce(deps.cwd, agentType);
+  return 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.
+ *
+ * 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.
+ */
+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);
+}
+
+/**
+ * True when `personaPath` (an already-resolved persona file path, e.g. from
+ * agentLibrary.cjs's getPersonaBody) is the PROJECT overlay candidate rather
+ * than the global one — the same "which of resolvePersonaPaths' two
+ * candidates won" question readModelFromCandidatePaths above answers
+ * structurally by trying the project path first. Exported so a caller that
+ * already has a resolved persona path from a DIFFERENT reader (one that
+ * needs async I/O or richer provenance than this module's sync
+ * readOverlayAwarePersonaModel returns — e.g. effectiveModelInfo.cjs) can
+ * ask this module the overlay question instead of re-deriving its own
+ * resolvePersonaPaths-based comparison. Never throws; a resolution failure
+ * conservatively answers "not overlay" (assume global).
+ */
+function isProjectOverlayPersonaPath(cwd, agentType, personaPath, deps = {}) {
+  if (!personaPath) return false;
   try {
-    text = fs.readFileSync(real, 'utf8');
+    const resolvePaths = deps.resolvePersonaPaths || resolvePersonaPaths;
+    const { projectPath } = resolvePaths(cwd, agentType, deps);
+    return Boolean(projectPath) && path.resolve(projectPath) === path.resolve(personaPath);
   } catch {
-    logDanglingPersonaOnce(deps.cwd, agentType);
-    return null;
+    return false;
   }
-  const { fm } = splitFrontmatter(text);
-  return fm.model || null;
 }
 
 /**
@@ -105,6 +168,12 @@ function readPersonaModel(agentType, deps = {}) {
  * file) falls back to `fallbackModel` (default: 'sonnet', the same literal
  * every claude -p call site pins per CLAUDE.md's model-pinning rule).
  *
+ * This is the SINGLE authority both Chat (`chatRunner.cjs`, in-process) and
+ * Terminal (`EpicTerminalPane.tsx`, via the `agents:resolve-epic-model` IPC
+ * added in the same change) call for an Epic-backed launch, so the two views
+ * of one Epic agree on which model that session launches with — see this
+ * module's header.
+ *
  * @param {{ cwd: string, claudeSessionId: string, fallbackModel?: string, deps?: object }} opts
  * @returns {string}
  */
@@ -112,7 +181,7 @@ function resolveEpicModel({ cwd, claudeSessionId, fallbackModel = FALLBACK_MODEL
   try {
     const agentType = findAgentTypeByClaudeSessionId(cwd, claudeSessionId, deps);
     if (!agentType) return fallbackModel;
-    const model = readPersonaModel(agentType, { ...deps, cwd });
+    const model = readOverlayAwarePersonaModel(agentType, { ...deps, cwd });
     if (!model || model === 'inherit') return fallbackModel;
     return model;
   } catch {
@@ -181,6 +250,7 @@ module.exports = {
   FALLBACK_MODEL,
   resolveEpicModel,
   findAgentTypeByClaudeSessionId,
-  readPersonaModel,
+  readOverlayAwarePersonaModel,
+  isProjectOverlayPersonaPath,
   resolvePrdPersonaForSpawn,
 };

package/src/main/lib/agentPersonaSchema.cjs

@@ -1,6 +1,6 @@
 /**
  * Canonical runtime schema for an Agent persona WRITE payload, mirroring the
- * TS `AgentPersonaSaveInput` interface at src/preload/api.d.ts:229-246
+ * TS `AgentPersonaSaveInput` interface in src/preload/api.d.ts
  * field-for-field.
  *
  * Modelled on promptSessionSchema.cjs / scheduleJobSchema.cjs's "zod schema
@@ -39,7 +39,7 @@ const ProjectEntrySchema = z.string().refine(
   `must be "${ALL_PROJECTS}" or an absolute path`,
 );
 
-// Mirrors AgentPersonaSaveInput (src/preload/api.d.ts:229-246). `tags` is the
+// Mirrors AgentPersonaSaveInput (src/preload/api.d.ts). `tags` is the
 // Epic-mission WorkType union, NOT a free-form string list — the same
 // concept as PromptSessionSchema's `tag` / scheduleRetagPrd's `tag`, just
 // plural here since a persona can be associated with more than one mission.

package/src/main/lib/auditLog.cjs

@@ -16,10 +16,9 @@
 'use strict';
 
 const fs = require('node:fs');
-const os = require('node:os');
 const path = require('node:path');
 
-const AUDIT_LOG_PATH = path.join(os.homedir(), '.claude', 'session-manager', 'audit-log.jsonl');
+const { auditLogPath } = require('./schedulerPaths.cjs');
 
 /**
  * Best-effort identity of the process making this call — there is no
@@ -50,11 +49,37 @@ function appendAuditEvent(kind, fields = {}) {
       ...fields,
       caller: callerContext(),
     };
-    fs.mkdirSync(path.dirname(AUDIT_LOG_PATH), { recursive: true });
-    fs.appendFileSync(AUDIT_LOG_PATH, `${JSON.stringify(record)}\n`);
+    const target = auditLogPath();
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.appendFileSync(target, `${JSON.stringify(record)}\n`);
   } catch (e) {
     console.error('[auditLog] failed to append audit event', e?.message ?? String(e));
   }
 }
 
-module.exports = { appendAuditEvent, AUDIT_LOG_PATH };
+/**
+ * readTail(maxBytes, target?) → string[] — the complete JSONL lines within the
+ * last `maxBytes` of the log, oldest first. O(maxBytes), never O(file): the
+ * audit log is a never-rotated provenance record and grows without bound. A
+ * line cut by the window's start is dropped. Missing/unreadable file → [].
+ */
+function readTail(maxBytes, target = auditLogPath()) {
+  let fd;
+  try {
+    fd = fs.openSync(target, 'r');
+    const { size } = fs.fstatSync(fd);
+    const readSize = Math.min(Math.max(0, maxBytes), size);
+    if (readSize === 0) return [];
+    const buf = Buffer.alloc(readSize);
+    fs.readSync(fd, buf, 0, readSize, size - readSize);
+    const lines = buf.toString('utf8').split('\n');
+    if (readSize < size) lines.shift(); // first element is a partial line
+    return lines.filter(Boolean);
+  } catch {
+    return [];
+  } finally {
+    if (fd !== undefined) { try { fs.closeSync(fd); } catch { /* */ } }
+  }
+}
+
+module.exports = { appendAuditEvent, auditLogPath, readTail };