claude-code-session-manager 0.73.2 → 0.75.0

package/src/main/index.cjs

@@ -36,6 +36,7 @@ const epicWorktreeMint = require('./lib/epicWorktreeMint.cjs');
 const epicWorktreeMerge = require('./lib/epicWorktreeMerge.cjs');
 const epicWorktreeProjectConfig = require('./lib/epicWorktreeProjectConfig.cjs');
 const agentLibrary = require('./agentLibrary.cjs');
+const { checkDelegationReadiness } = require('./lib/delegationReadiness.cjs');
 const { sendIfAlive } = require('./lib/sendToRenderer.cjs');
 const { resolveBuildTarget } = require('./lib/buildTarget.cjs');
 const crossProjectFeedback = require('./lib/crossProjectFeedback.cjs');
@@ -54,6 +55,9 @@ const teams = require('./teams.cjs');
 const queueOps = require('./queueOps.cjs');
 const pluginInstall = require('./pluginInstall.cjs');
 const { seedDevPlugin } = require('./seedDevPlugin.cjs');
+const { seedAgentPersonas } = require('./seedAgentPersonas.cjs');
+const { seedSchedulerMcp } = require('./seedSchedulerMcp.cjs');
+const { getSeedStatus } = require('./seedStatus.cjs');
 const otel = require('./otel.cjs');
 const otelSettings = require('./otelSettings.cjs');
 const { registerHistoryAggregatorHandlers, finalizeClosedDays, refreshIntradayToday } = require('./historyAggregator.cjs');
@@ -67,6 +71,7 @@ const { registerProjectBriefIpc } = require('./projectBrief.cjs');
 const { registerProjectPagesIpc } = require('./projectPages.cjs');
 const { registerBilkoHostIpc } = require('./bilkoHost.cjs');
 const promptSessionTranscript = require('./promptSessionTranscript.cjs');
+const { computeEpicDelegationStats } = require('./lib/epicDelegationStats.cjs');
 const agentMemory = require('./agentMemory.cjs');
 const git = require('./git.cjs');
 const heapSnapshot = require('./heapSnapshot.cjs');
@@ -466,11 +471,11 @@ ipcMain.handle('agents:list-personas', () => agentLibrary.listPersonas());
 function broadcastAgentsChanged() {
   sendIfAlive(mainWindow, 'agents:changed', {});
 }
-ipcMain.handle('agents:save-persona', async (_e, payload) => {
+ipcMain.handle('agents:save-persona', validated(schemas.agentsSavePersona, async (payload) => {
   const result = await agentLibrary.savePersona(payload);
   broadcastAgentsChanged();
   return result;
-});
+}));
 ipcMain.handle('agents:delete-persona', async (_e, payload) => {
   const result = await agentLibrary.deletePersona(payload);
   broadcastAgentsChanged();
@@ -481,6 +486,19 @@ ipcMain.handle('agents:remove-override', async (_e, payload) => {
   broadcastAgentsChanged();
   return result;
 });
+// New Epic AIM composer (epicIntake.ts's `agentBody`/`agentPath`): unlike
+// list-personas above (global dir only), this honors the project-overlay-
+// then-global precedence so an Epic's opening prompt carries the persona
+// body that actually applies to its cwd. Read-only.
+ipcMain.handle('agents:get-persona-body', validated(schemas.agentsGetPersonaBody, (payload) =>
+  agentLibrary.getPersonaBody(payload)));
+
+// "Can this project actually delegate?" probe (PRD: delegation-readiness).
+// Structured data over the four preconditions for scheduler_create_prd being
+// in an agent's tool list at all — surfacing it in the UI is a sibling PRD.
+ipcMain.handle('app:delegation-readiness', validated(schemas.delegationReadinessCwd, (payload) =>
+  checkDelegationReadiness(payload)
+));
 
 ipcMain.handle('app:engage-rules-path', () => process.env.SESSION_MANAGER_ENGAGE_RULES || null);
 
@@ -488,6 +506,9 @@ ipcMain.handle('app:engage-rules-path', () => process.env.SESSION_MANAGER_ENGAGE
 // on disk or the home self-check failed (e.g. macOS /Users symlink mismatch).
 ipcMain.handle('app:claude-bin-status', () => bootClaudeBin);
 ipcMain.handle('app:home-self-check', () => bootHomeSelfCheck);
+// First-boot seeder outcomes ('done' | 'pending' | 'exhausted' per seeder),
+// read live from each seeder's own marker file — see seedStatus.cjs.
+ipcMain.handle('app:seed-status', () => getSeedStatus());
 
 ipcMain.handle('app:pick-directory', async () => {
   console.log('[main] pick-directory invoked');
@@ -802,6 +823,11 @@ ipcMain.handle('promptSessionTranscript:read', validated(schemas.promptSessionTr
   const turns = await promptSessionTranscript.readTurns(cwd, epicId, { limit });
   return { turns };
 }));
+// Derived-at-read-time "PRDs queued vs inline edits" counter (no writer —
+// reads the Epic's own live prds/ dir + its own claude session transcript).
+ipcMain.handle('epicDelegationStats:get', validated(schemas.epicDelegationStatsGet, async ({ cwd, epicId, claudeSessionId }) => {
+  return computeEpicDelegationStats(cwd, epicId, claudeSessionId || null);
+}));
 // Renderer Epic lifecycle trace (PRD 940) — append-only, no read/list IPC.
 // Kind allowlist enforced by schemas.auditLogAppend, not here.
 ipcMain.handle('auditLog:append', validated(schemas.auditLogAppend, async ({ kind, cwd, epicId, source }) => {
@@ -1149,9 +1175,24 @@ app.whenReady().then(async () => {
   // First-boot default: install the bundled session-manager-dev plugin (its 10
   // dev skills) from the app's own marketplace. One-shot + idempotent; never
   // throws. SM_SEED_DEV_PLUGIN_DISABLE=1 to opt out.
-  seedDevPlugin({ logger: console }).catch((e) => {
+  seedDevPlugin({ logger: console, writeLog: logs.writeLine }).catch((e) => {
     logs.writeLine({ scope: 'seed-dev-plugin', level: 'error', message: 'seed failed', meta: { error: e?.message } });
   });
+  // First-boot default: seed the bundled Architect + Dev Lead Agent personas
+  // into ~/.claude/agents/ so the Agent Library isn't empty on a fresh
+  // install. One-shot + idempotent; never overwrites an existing persona;
+  // never throws. SM_SEED_AGENT_PERSONAS_DISABLE=1 to opt out.
+  seedAgentPersonas({ logger: console, writeLog: logs.writeLine }).catch((e) => {
+    logs.writeLine({ scope: 'seed-agent-personas', level: 'error', message: 'seed failed', meta: { error: e?.message } });
+  });
+  // First-boot default: register the session-manager-scheduler MCP server at
+  // USER scope so scheduler_create_prd is available in every project, not
+  // just this repo's own .mcp.json. One-shot + idempotent; never overwrites
+  // an existing registration; never throws. SM_SEED_SCHEDULER_MCP_DISABLE=1
+  // to opt out.
+  seedSchedulerMcp({ logger: console, writeLog: logs.writeLine }).catch((e) => {
+    logs.writeLine({ scope: 'seed-scheduler-mcp', level: 'error', message: 'seed failed', meta: { error: e?.message } });
+  });
   // History rollup finalize pass: deferred 30s past boot so it never competes
   // with first-paint, fire-and-forget (cron/offline refresh is PRD 651 — this
   // is just the one-shot in-app pass).

package/src/main/ipcSchemas.cjs

@@ -9,6 +9,8 @@ const { z } = require('zod');
 const os = require('node:os');
 const path = require('node:path');
 const { PromptSessionSchema, EpicTagSchema, EpicSourceSchema, EpicIntakeSectionSchema } = require('./lib/promptSessionSchema.cjs');
+const { PrdWorkTypeSchema } = require('./lib/workTypeLibrary.cjs');
+const { AgentPersonaSaveSchema } = require('./lib/agentPersonaSchema.cjs');
 
 // ──────────────────────────────────────────── PTY
 const ptySpawn = z.object({
@@ -331,13 +333,13 @@ const schedulerCreatePrd = z.object({
   // within an Epic's own chat session joins that Epic even if the tool call
   // forgot to pass sourcePromptId explicitly.
   originClaudeSessionId: z.string().min(1).max(128).regex(NO_NEWLINE_RE, 'must not contain newlines').optional(),
-  // User-selected Feature/Bug tag (PRD 774) carried from the originating
-  // PromptTicket — deterministic, never LLM-classified. NOT the same value
-  // set as PromptSession's Epic-mission `tag` (lib/promptSessionSchema.cjs's
-  // EpicTagSchema) — that one also includes 'bilko-host-publisher'. Keep
-  // these two enums in sync deliberately if their meanings ever converge;
-  // don't assume editing one updates the other.
-  tag: z.enum(['feature', 'bug', 'discussion', 'build', 'project-home-builder']).optional(),
+  // User-selected work-type tag (PRD 774; independence from the parent
+  // Epic's own tag confirmed PRD 1041) — deterministic, never LLM-classified.
+  // Epic tag and PRD tag draw on the same WorkType vocabulary
+  // (lib/workTypeLibrary.cjs) but are independent values; 'discussion' is
+  // excluded here for the same reason adminPrdFrontmatterPatch excludes it
+  // below — a discussion-tagged Epic never reaches PRD authoring.
+  tag: PrdWorkTypeSchema.optional(),
 });
 
 // Bulk archive: slug list, capped to limit unbounded retag/archive payloads.
@@ -387,8 +389,9 @@ const adminPrdFrontmatterPatch = z.object({
   sourceTabId: z.string().min(1).max(128).regex(NO_NEWLINE_RE, 'must not contain newlines').optional(),
   // 'discussion' deliberately excluded: matches prdFrontmatter.cjs's
   // parsePrdFile, which never parses that value for a PRD's tag key (a
-  // discussion-tagged Epic never reaches PRD authoring).
-  tag: z.enum(['feature', 'bug', 'build']).optional(),
+  // discussion-tagged Epic never reaches PRD authoring) — see
+  // workTypeLibrary.cjs's PrdWorkTypeSchema.
+  tag: PrdWorkTypeSchema.optional(),
   // Provenance stamp (PRD-authoring lockdown). Free-text rather than an enum
   // — 'scheduler-api' (create-time) and 'legacy-adopted' (migration/manual
   // adopt) are the two values this codebase writes today, but the field
@@ -464,6 +467,14 @@ const setSessionSlotsSchema = z.object({
   cap: z.number().int().min(0).max(10),
 }).strict();
 
+// ──────────────────────────────────────────── Agent Library
+// agents:save-persona — the Agent entity (Agent/WorkType/Epic/PRD/Job ERD)
+// had no boundary validation until this schema; Epic and Job each got theirs
+// only after a production incident (see scheduleJobSchema.cjs's header).
+// Full field-level rules live in lib/agentPersonaSchema.cjs, mirroring
+// AgentPersonaSaveInput (src/preload/api.d.ts) field-for-field.
+const agentsSavePersona = AgentPersonaSaveSchema;
+
 // ──────────────────────────────────────────── Memory tool (Bundle C, cycle 3)
 // Workspace-scoped markdown store at ~/.claude/projects/<ws>/memory/.
 // Slug regex is shared with memoryTool.cjs/memoryAggregate.cjs via lib/memorySlug.cjs;
@@ -526,6 +537,17 @@ const projectBriefCwd = z.object({
   cwd: z.string().min(1).max(4096),
 }).strict();
 
+// ──────────────────────────────────────────── Delegation readiness
+const delegationReadinessCwd = z.object({
+  cwd: z.string().min(1).max(4096),
+}).strict();
+
+// ──────────────────────────────────────────── Agent persona body (New Epic AIM)
+const agentsGetPersonaBody = z.object({
+  cwd: z.string().min(1).max(4096),
+  name: z.string().min(1).max(200),
+}).strict();
+
 // ──────────────────────────────────────────── Project Pages (PRD 932)
 // Same validation split as projectBriefCwd above: real path validation is
 // config.cjs's validatePath at first fs access in projectPages.cjs.
@@ -597,6 +619,17 @@ const promptSessionTranscriptRead = z.object({
   limit: z.number().int().positive().max(10_000).optional(),
 }).strict();
 
+// ──────────────────────────────────────────── Epic delegation stats
+// (derived-at-read-time "PRDs queued vs inline edits" counter surfaced on
+// the Epic card). claudeSessionId is optional — a proposed Epic that never
+// started chatting has none, and the computation just reports 0 inline
+// edits rather than throwing.
+const epicDelegationStatsGet = z.object({
+  cwd: z.string().min(1).max(4096),
+  epicId: z.string().regex(PROMPT_SESSION_EPIC_ID_RE),
+  claudeSessionId: z.string().max(128).optional().nullable(),
+}).strict();
+
 // ──────────────────────────────────────────── Audit log (renderer Epic
 // lifecycle trace, PRD 940). Kind allowlist is enforced HERE, main-side — the
 // renderer cannot write arbitrary kinds through this channel, only the six
@@ -938,6 +971,7 @@ module.exports = {
     projectBriefUpdate,
     promptSessionTranscriptAppend,
     promptSessionTranscriptRead,
+    epicDelegationStatsGet,
     promptSessionsMergeActiveIndex,
     promptSessionsCreateEpic,
     promptSessionsCreateWorktree,
@@ -962,6 +996,9 @@ module.exports = {
     chatClassifyTicket,
     chatExternalSend,
     exchangesList,
+    agentsSavePersona,
+    agentsGetPersonaBody,
+    delegationReadinessCwd,
   },
   validated,
 };

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

@@ -0,0 +1,67 @@
+/**
+ * agentPersonaSchema.test.cjs — unit tests for the canonical Agent persona
+ * WRITE-path zod schema and its assertValidAgentPersonaSave fail-closed
+ * helper.
+ *
+ * Agent is the third entity in the Agent/WorkType/Epic/PRD/Job ERD to get a
+ * boundary schema — Epic (promptSessionSchema.cjs) and Job
+ * (scheduleJobSchema.cjs) each got theirs only after a production incident;
+ * this one closes the gap proactively before Agent has had its own.
+ *
+ * Run: timeout 120 npx vitest run src/main/lib/__tests__/agentPersonaSchema.test.cjs
+ */
+
+'use strict';
+
+import { test, expect } from 'vitest';
+const {
+  AgentPersonaSaveSchema,
+  assertValidAgentPersonaSave,
+} = require('../agentPersonaSchema.cjs');
+
+function validPersona(overrides = {}) {
+  return {
+    name: 'code-reviewer',
+    description: 'Reviews diffs for correctness and style.',
+    tools: ['Read', 'Grep', 'Glob'],
+    model: 'inherit',
+    color: 'blue',
+    tags: ['feature', 'bug'],
+    projects: ['*'],
+    action: '/develop\n\nReview the current diff.',
+    actionLabel: 'Review',
+    title: 'Engineering — Code Reviewer',
+    body: 'You are a meticulous code reviewer.',
+    ...overrides,
+  };
+}
+
+test('a valid full persona parses', () => {
+  const full = validPersona();
+  expect(() => assertValidAgentPersonaSave(full)).not.toThrow();
+  expect(AgentPersonaSaveSchema.safeParse(full).success).toBe(true);
+});
+
+test('a persona with an unknown tag is rejected', () => {
+  const badTag = validPersona({ tags: ['feature', 'not-a-real-worktype'] });
+  expect(() => assertValidAgentPersonaSave(badTag)).toThrow(/tags/);
+});
+
+test('a persona with an uppercase/spaced name is rejected', () => {
+  const badName = validPersona({ name: 'Code Reviewer' });
+  expect(() => assertValidAgentPersonaSave(badName)).toThrow(/name/);
+});
+
+test('a persona with only the required fields parses', () => {
+  const minimal = {
+    name: 'minimal-agent',
+    description: '',
+    tools: [],
+    model: 'inherit',
+    color: '',
+    tags: [],
+    body: '',
+  };
+  expect(() => assertValidAgentPersonaSave(minimal)).not.toThrow();
+  expect(AgentPersonaSaveSchema.safeParse(minimal).success).toBe(true);
+});

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

@@ -0,0 +1,185 @@
+/**
+ * delegationReadiness.test.cjs — unit tests for the "can this project
+ * actually delegate?" probe. Uses a temp HOME and a temp cwd so the real
+ * ~/.claude and this repo's own config are never touched.
+ *
+ * Run: timeout 300 npx vitest run src/main/lib/__tests__/delegationReadiness.test.cjs
+ */
+
+import { test, expect, afterEach } from 'vitest';
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+const { checkDelegationReadiness } = require('../delegationReadiness.cjs');
+
+const tmpDirs = [];
+afterEach(async () => {
+  while (tmpDirs.length) {
+    const d = tmpDirs.pop();
+    await fsp.rm(d, { recursive: true, force: true });
+  }
+});
+
+async function mkTmp(prefix) {
+  const d = await fsp.mkdtemp(path.join(os.tmpdir(), prefix));
+  tmpDirs.push(d);
+  return d;
+}
+
+async function writeJson(absPath, value) {
+  await fsp.mkdir(path.dirname(absPath), { recursive: true });
+  await fsp.writeFile(absPath, JSON.stringify(value), 'utf8');
+}
+
+async function makeGreenFixtures() {
+  const homeDir = await mkTmp('sm-delegation-home-');
+  const cwd = await mkTmp('sm-delegation-cwd-');
+
+  await writeJson(path.join(homeDir, '.claude.json'), {
+    mcpServers: { 'session-manager-scheduler': { type: 'stdio', command: 'node', args: [] } },
+  });
+  await writeJson(path.join(homeDir, '.claude', 'settings.json'), {
+    enabledPlugins: { 'session-manager-dev@session-manager': true },
+  });
+  await fsp.mkdir(path.join(homeDir, '.claude', 'agents'), { recursive: true });
+  await fsp.writeFile(path.join(homeDir, '.claude', 'agents', 'dev-lead.md'), '# dev-lead', 'utf8');
+  await writeJson(path.join(cwd, '.claude', 'settings.json'), {
+    hooks: {
+      PreToolUse: [
+        {
+          matcher: 'Write|Edit|NotebookEdit',
+          hooks: [{ type: 'command', command: 'node scripts/hooks/guard-prd-writes.cjs' }],
+        },
+      ],
+    },
+  });
+
+  return { homeDir, cwd };
+}
+
+test('all four checks pass on a fully-configured project', async () => {
+  const { homeDir, cwd } = await makeGreenFixtures();
+  const result = checkDelegationReadiness({ cwd, homeDir });
+
+  expect(result.ok).toBe(true);
+  expect(result.checks).toHaveLength(4);
+  expect(result.checks.every((c) => c.ok)).toBe(true);
+  expect(result.checks.map((c) => c.id)).toEqual([
+    'scheduler-mcp',
+    'dev-plugin',
+    'agent-personas',
+    'prd-write-guard',
+  ]);
+});
+
+test('scheduler-mcp: passes via project-scope .mcp.json even without user scope', async () => {
+  const { homeDir, cwd } = await makeGreenFixtures();
+  await writeJson(path.join(homeDir, '.claude.json'), { mcpServers: {} });
+  await writeJson(path.join(cwd, '.mcp.json'), {
+    mcpServers: { 'session-manager-scheduler': { command: 'node', args: [] } },
+  });
+
+  const result = checkDelegationReadiness({ cwd, homeDir });
+  const check = result.checks.find((c) => c.id === 'scheduler-mcp');
+  expect(check.ok).toBe(true);
+  expect(result.ok).toBe(true);
+});
+
+test('scheduler-mcp: fails with a runnable fix when absent from both scopes', async () => {
+  const { homeDir, cwd } = await makeGreenFixtures();
+  await writeJson(path.join(homeDir, '.claude.json'), { mcpServers: {} });
+
+  const result = checkDelegationReadiness({ cwd, homeDir });
+  const check = result.checks.find((c) => c.id === 'scheduler-mcp');
+  expect(check.ok).toBe(false);
+  expect(result.ok).toBe(false);
+  expect(check.fix).toMatch(/^claude mcp add session-manager-scheduler --scope user/);
+  expect(check.fix).toContain('scheduler-mcp-server.cjs');
+});
+
+test('dev-plugin: fails independently when enabledPlugins is missing the key', async () => {
+  const { homeDir, cwd } = await makeGreenFixtures();
+  await writeJson(path.join(homeDir, '.claude', 'settings.json'), { enabledPlugins: {} });
+
+  const result = checkDelegationReadiness({ cwd, homeDir });
+  const check = result.checks.find((c) => c.id === 'dev-plugin');
+  expect(check.ok).toBe(false);
+  expect(result.ok).toBe(false);
+  expect(check.fix).toBeTruthy();
+  // the other three checks still pass independently
+  expect(result.checks.filter((c) => c.id !== 'dev-plugin').every((c) => c.ok)).toBe(true);
+});
+
+test('agent-personas: fails independently when ~/.claude/agents has no personas', async () => {
+  const { homeDir, cwd } = await makeGreenFixtures();
+  await fsp.rm(path.join(homeDir, '.claude', 'agents', 'dev-lead.md'));
+
+  const result = checkDelegationReadiness({ cwd, homeDir });
+  const check = result.checks.find((c) => c.id === 'agent-personas');
+  expect(check.ok).toBe(false);
+  expect(result.ok).toBe(false);
+  expect(result.checks.filter((c) => c.id !== 'agent-personas').every((c) => c.ok)).toBe(true);
+});
+
+test('agent-personas: passes via project-scope .claude/agents/ even without global personas', async () => {
+  const { homeDir, cwd } = await makeGreenFixtures();
+  await fsp.rm(path.join(homeDir, '.claude', 'agents'), { recursive: true, force: true });
+  await fsp.mkdir(path.join(cwd, '.claude', 'agents'), { recursive: true });
+  await fsp.writeFile(path.join(cwd, '.claude', 'agents', 'builder.md'), '# builder', 'utf8');
+
+  const result = checkDelegationReadiness({ cwd, homeDir });
+  const check = result.checks.find((c) => c.id === 'agent-personas');
+  expect(check.ok).toBe(true);
+  expect(result.ok).toBe(true);
+});
+
+test('agent-personas: fails when the directory does not exist at all', async () => {
+  const { homeDir, cwd } = await makeGreenFixtures();
+  await fsp.rm(path.join(homeDir, '.claude', 'agents'), { recursive: true, force: true });
+
+  const result = checkDelegationReadiness({ cwd, homeDir });
+  const check = result.checks.find((c) => c.id === 'agent-personas');
+  expect(check.ok).toBe(false);
+});
+
+test('prd-write-guard: fails independently when the hook is missing', async () => {
+  const { homeDir, cwd } = await makeGreenFixtures();
+  await writeJson(path.join(cwd, '.claude', 'settings.json'), { hooks: { PreToolUse: [] } });
+
+  const result = checkDelegationReadiness({ cwd, homeDir });
+  const check = result.checks.find((c) => c.id === 'prd-write-guard');
+  expect(check.ok).toBe(false);
+  expect(result.ok).toBe(false);
+  expect(result.checks.filter((c) => c.id !== 'prd-write-guard').every((c) => c.ok)).toBe(true);
+});
+
+test('unparseable JSON files yield ok:false with a detail, never a throw', async () => {
+  const { homeDir, cwd } = await makeGreenFixtures();
+  await fs.promises.writeFile(path.join(homeDir, '.claude.json'), '{ not valid json', 'utf8');
+  await fs.promises.writeFile(path.join(homeDir, '.claude', 'settings.json'), '{ not valid json', 'utf8');
+  await fs.promises.writeFile(path.join(cwd, '.claude', 'settings.json'), '{ not valid json', 'utf8');
+
+  expect(() => checkDelegationReadiness({ cwd, homeDir })).not.toThrow();
+  const result = checkDelegationReadiness({ cwd, homeDir });
+
+  const scheduler = result.checks.find((c) => c.id === 'scheduler-mcp');
+  const devPlugin = result.checks.find((c) => c.id === 'dev-plugin');
+  const guard = result.checks.find((c) => c.id === 'prd-write-guard');
+  expect(scheduler.ok).toBe(false);
+  expect(scheduler.detail).toBeTruthy();
+  expect(devPlugin.ok).toBe(false);
+  expect(devPlugin.detail).toBeTruthy();
+  expect(guard.ok).toBe(false);
+  expect(guard.detail).toBeTruthy();
+  expect(result.ok).toBe(false);
+});
+
+test('missing cwd/.claude/settings.json entirely is treated as guard-absent, not a throw', async () => {
+  const { homeDir, cwd } = await makeGreenFixtures();
+  await fsp.rm(path.join(cwd, '.claude', 'settings.json'));
+
+  expect(() => checkDelegationReadiness({ cwd, homeDir })).not.toThrow();
+  const result = checkDelegationReadiness({ cwd, homeDir });
+  expect(result.checks.find((c) => c.id === 'prd-write-guard').ok).toBe(false);
+});

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

@@ -0,0 +1,137 @@
+/**
+ * epicDelegationStats.test.cjs — unit tests for the derived-at-read-time
+ * "did this Epic delegate?" counters (prdsQueued from the Epic's own live
+ * PRD dir, inlineEdits from its interactive claude session transcript).
+ *
+ * Run: timeout 120 npx vitest run src/main/lib/__tests__/epicDelegationStats.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, afterEach } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const {
+  computeEpicDelegationStats,
+  countPrdsQueued,
+  countInlineEdits,
+  isApplicationSourcePath,
+} = require('../epicDelegationStats.cjs');
+const { encodeCwd } = require('../encodeCwd.cjs');
+
+const tmpDirs = [];
+function makeTmpCwd() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'epic-delegation-'));
+  tmpDirs.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  while (tmpDirs.length) {
+    fs.rmSync(tmpDirs.pop(), { recursive: true, force: true });
+  }
+});
+
+function makeTmpHome() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'epic-delegation-home-'));
+  tmpDirs.push(dir);
+  return dir;
+}
+
+function writeTranscript(homeDir, cwd, sessionId, lines) {
+  const dir = path.join(homeDir, '.claude', 'projects', encodeCwd(cwd));
+  fs.mkdirSync(dir, { recursive: true });
+  const filePath = path.join(dir, `${sessionId}.jsonl`);
+  fs.writeFileSync(filePath, lines.map((l) => JSON.stringify(l)).join('\n') + '\n');
+  return filePath;
+}
+
+function toolUseLine(name, filePath) {
+  return {
+    type: 'assistant',
+    message: { content: [{ type: 'tool_use', name, id: 't1', input: { file_path: filePath } }] },
+  };
+}
+
+test('countPrdsQueued counts only .md files in the Epic own live prds dir', () => {
+  const cwd = makeTmpCwd();
+  const prdsDir = path.join(cwd, 'session-manager-operations', 'scheduler', 'epics', 'epic-1', 'prds');
+  fs.mkdirSync(prdsDir, { recursive: true });
+  fs.writeFileSync(path.join(prdsDir, '01-foo.md'), '# foo');
+  fs.writeFileSync(path.join(prdsDir, '02-bar.md'), '# bar');
+  fs.writeFileSync(path.join(prdsDir, '.reserved-03'), '');
+  expect(countPrdsQueued(cwd, 'epic-1')).toBe(2);
+});
+
+test('countPrdsQueued returns 0 when the prds dir does not exist', () => {
+  const cwd = makeTmpCwd();
+  expect(countPrdsQueued(cwd, 'missing-epic')).toBe(0);
+});
+
+test('isApplicationSourcePath matches src/scripts/plugins/bin, rejects everything else', () => {
+  const cwd = '/repo';
+  expect(isApplicationSourcePath(cwd, '/repo/src/main/index.cjs')).toBe(true);
+  expect(isApplicationSourcePath(cwd, '/repo/scripts/hooks/foo.cjs')).toBe(true);
+  expect(isApplicationSourcePath(cwd, '/repo/plugins/dev/skill.md')).toBe(true);
+  expect(isApplicationSourcePath(cwd, '/repo/bin/cli.cjs')).toBe(true);
+  expect(isApplicationSourcePath(cwd, '/repo/session-manager-operations/scheduler/epics/e1/prds/01.md')).toBe(false);
+  expect(isApplicationSourcePath(cwd, '/repo/README.md')).toBe(false);
+  expect(isApplicationSourcePath(cwd, '/outside/src/index.cjs')).toBe(false);
+  expect(isApplicationSourcePath(cwd, undefined)).toBe(false);
+});
+
+test('countInlineEdits counts Write/Edit/NotebookEdit tool_use blocks under application source only', () => {
+  const cwd = makeTmpCwd();
+  const homeDir = makeTmpHome();
+  writeTranscript(homeDir, cwd, 'sess-1', [
+    toolUseLine('Write', path.join(cwd, 'src', 'main', 'foo.cjs')),
+    toolUseLine('Edit', path.join(cwd, 'src', 'main', 'foo.cjs')),
+    toolUseLine('Read', path.join(cwd, 'src', 'main', 'foo.cjs')),
+    toolUseLine('Write', path.join(cwd, 'session-manager-operations', 'scheduler', 'epics', 'e1', 'prds', '01.md')),
+    toolUseLine('NotebookEdit', path.join(cwd, 'scripts', 'nb.ipynb')),
+  ]);
+  expect(countInlineEdits(cwd, 'sess-1', { homeDir })).toBe(3);
+});
+
+test('countInlineEdits returns 0 when the transcript file does not exist', () => {
+  const cwd = makeTmpCwd();
+  const homeDir = makeTmpHome();
+  expect(countInlineEdits(cwd, 'no-such-session', { homeDir })).toBe(0);
+});
+
+test('countInlineEdits returns 0 when claudeSessionId is missing', () => {
+  const cwd = makeTmpCwd();
+  expect(countInlineEdits(cwd, null)).toBe(0);
+});
+
+test('countInlineEdits tolerates a malformed trailing line', () => {
+  const cwd = makeTmpCwd();
+  const homeDir = makeTmpHome();
+  const dir = path.join(homeDir, '.claude', 'projects', encodeCwd(cwd));
+  fs.mkdirSync(dir, { recursive: true });
+  const filePath = path.join(dir, 'sess-2.jsonl');
+  fs.writeFileSync(
+    filePath,
+    JSON.stringify(toolUseLine('Write', path.join(cwd, 'src', 'a.ts'))) + '\n{not json\n',
+  );
+  expect(countInlineEdits(cwd, 'sess-2', { homeDir })).toBe(1);
+});
+
+test('computeEpicDelegationStats combines both counters and never throws on missing state', () => {
+  const cwd = makeTmpCwd();
+  const homeDir = makeTmpHome();
+  expect(computeEpicDelegationStats(cwd, 'ghost-epic', 'ghost-session', { homeDir })).toEqual({
+    prdsQueued: 0,
+    inlineEdits: 0,
+  });
+
+  const prdsDir = path.join(cwd, 'session-manager-operations', 'scheduler', 'epics', 'epic-2', 'prds');
+  fs.mkdirSync(prdsDir, { recursive: true });
+  fs.writeFileSync(path.join(prdsDir, '01-foo.md'), '# foo');
+  writeTranscript(homeDir, cwd, 'sess-3', [toolUseLine('Edit', path.join(cwd, 'src', 'x.ts'))]);
+  expect(computeEpicDelegationStats(cwd, 'epic-2', 'sess-3', { homeDir })).toEqual({
+    prdsQueued: 1,
+    inlineEdits: 1,
+  });
+});

package/src/main/lib/agentModelResolve.cjs

@@ -27,6 +27,35 @@ 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"). */
 const FALLBACK_MODEL = 'sonnet';
 
+// READ side of the agentType FK (write side: epicMint.cjs's ensureEpic —
+// "throw on write, report on read"). A persona can legitimately be renamed
+// or deleted after an Epic was created against it; that Epic must keep
+// loading (this module's whole contract is "never throws"), but the
+// dangling reference should still be visible somewhere. Logged at most once
+// per (cwd, agentType) so a headless launch that resolves the same Epic's
+// model on every turn doesn't flood opsErrorLog's daily file.
+const loggedDanglingPersonas = new Set();
+
+function logDanglingPersonaOnce(cwd, agentType) {
+  if (!cwd || !agentType) return;
+  const key = `${cwd}::${agentType}`;
+  if (loggedDanglingPersonas.has(key)) return;
+  loggedDanglingPersonas.add(key);
+  try {
+    // Required lazily: opsErrorLog.cjs is a leaf module with no Electron
+    // dependency, but keeping this require inside the miss path avoids
+    // paying for it on the (overwhelmingly common) hit path.
+    const { appendError } = require('./opsErrorLog.cjs');
+    appendError({
+      cwd,
+      scope: 'agentModelResolve',
+      level: 'warn',
+      message: `agentType '${agentType}' has no resolvable persona file — model resolution fell back to '${FALLBACK_MODEL}'`,
+      meta: { agentType },
+    });
+  } catch { /* logging must never break model resolution */ }
+}
+
 /**
  * Looks up the agentType an Epic (PromptSession) was created with, by the
  * Epic's own claudeSessionId — the same domain-model join `prdCreate.cjs`'s
@@ -56,12 +85,14 @@ function readPersonaModel(agentType, deps = {}) {
   try {
     real = validatePath(path.join(globalDir, `${agentType}.md`));
   } catch {
+    logDanglingPersonaOnce(deps.cwd, agentType);
     return null;
   }
   let text;
   try {
     text = fs.readFileSync(real, 'utf8');
   } catch {
+    logDanglingPersonaOnce(deps.cwd, agentType);
     return null;
   }
   const { fm } = splitFrontmatter(text);
@@ -81,7 +112,7 @@ function resolveEpicModel({ cwd, claudeSessionId, fallbackModel = FALLBACK_MODEL
   try {
     const agentType = findAgentTypeByClaudeSessionId(cwd, claudeSessionId, deps);
     if (!agentType) return fallbackModel;
-    const model = readPersonaModel(agentType, deps);
+    const model = readPersonaModel(agentType, { ...deps, cwd });
     if (!model || model === 'inherit') return fallbackModel;
     return model;
   } catch {