claude-code-session-manager 0.73.2 → 0.75.0

package/src/main/__tests__/health-claude-md-budget.test.cjs

@@ -0,0 +1,57 @@
+/**
+ * health-claude-md-budget.test.cjs — CLAUDE.md SIZE BUDGET enforcement
+ * (PRD 1039, following CLAUDE.md's growth from 3,871 to 65,768 chars between
+ * 2026-05-09 and 2026-08-13 with zero of 359 PRDs ever pruning it). Exercises
+ * parseClaudeMdBudget()/evaluateClaudeMdBudget() directly since they're pure —
+ * no need to spawn the full check() to cover this.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/health-claude-md-budget.test.cjs
+ */
+
+'use strict';
+
+import { test, expect } from 'vitest';
+const { parseClaudeMdBudget, evaluateClaudeMdBudget } = require('../health.cjs');
+
+test('under budget reports ok with no issue', () => {
+  const result = evaluateClaudeMdBudget(11873, 12000);
+  expect(result.ok).toBe(true);
+  expect(result.applicable).toBe(true);
+  expect(result.message).toBeUndefined();
+});
+
+test('exactly at budget reports ok with no issue', () => {
+  const result = evaluateClaudeMdBudget(12000, 12000);
+  expect(result.ok).toBe(true);
+  expect(result.applicable).toBe(true);
+});
+
+test('over budget reports one issue with actual size and budget in the message', () => {
+  const result = evaluateClaudeMdBudget(13210, 12000);
+  expect(result.ok).toBe(false);
+  expect(result.overage).toBe(1210);
+  expect(result.message).toContain('13210');
+  expect(result.message).toContain('12000');
+  expect(result.message).toContain('1210');
+});
+
+test('no SIZE BUDGET line present -> parses to null, evaluator skips silently', () => {
+  const text = '# Some Project\n\nJust a normal CLAUDE.md with no budget declared.\n';
+  const budget = parseClaudeMdBudget(text);
+  expect(budget).toBeNull();
+  const result = evaluateClaudeMdBudget(50000, budget);
+  expect(result.ok).toBe(true);
+  expect(result.applicable).toBe(false);
+});
+
+test('malformed/unparseable budget line -> null, no throw', () => {
+  const text = '> **SIZE BUDGET — a lot of chars**, checked before every commit.';
+  expect(() => parseClaudeMdBudget(text)).not.toThrow();
+  const budget = parseClaudeMdBudget(text);
+  expect(budget).toBeNull();
+});
+
+test('comma-separated form parses to a plain integer', () => {
+  const text = '> **SIZE BUDGET — 12,000 chars**, checked with `wc -c CLAUDE.md` before every commit.';
+  expect(parseClaudeMdBudget(text)).toBe(12000);
+});

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

@@ -512,6 +512,23 @@ test('POST /admin/scheduler/create-prd with sourcePromptId writes it into the cr
   }
 });
 
+test('POST /admin/scheduler/create-prd with tag writes it into the created PRD frontmatter (PRD 1041)', async () => {
+  const prdsDir = await mkTmpPrdsDir();
+  const remote = makeFakeRemoteWithPrdsDir(prdsDir);
+  const { admin, port, token } = await startWithRemote(remote);
+  try {
+    const res = await request(port, {
+      method: 'POST', path: '/admin/scheduler/create-prd', token,
+      body: validCreateBody({ slug: 'with-a-tag', tag: 'bug' }),
+    });
+    expect(res.status).toBe(200);
+    const written = fs.readFileSync(path.join(prdsDir, `${res.json.nn}-with-a-tag.md`), 'utf8');
+    expect(written).toMatch(/^tag: bug$/m);
+  } finally {
+    await admin.stop();
+  }
+});
+
 // ──────────────────────────────────────────── originClaudeSessionId fallback
 // (2026-08-01 fix: a PRD queued via the scheduler_create_prd MCP tool from
 // inside an Epic's own chat session, without an explicit sourcePromptId,

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

@@ -16,6 +16,7 @@
 'use strict';
 
 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');
@@ -40,6 +41,12 @@ async function mkCwd() {
   const cwd = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-promptsessions-create-epic-'));
   config.addAllowedRoot(cwd);
   tmpDirs.push(cwd);
+  // Project-overlay fixture so the 'architect' agentType used below resolves
+  // via ensureEpic's write-time persona-existence check without depending on
+  // the host's ~/.claude/agents/ (epicMint.cjs).
+  const agentsDir = path.join(cwd, '.claude', 'agents');
+  fs.mkdirSync(agentsDir, { recursive: true });
+  fs.writeFileSync(path.join(agentsDir, 'architect.md'), '---\nname: architect\n---\nFixture persona for tests.\n');
   return cwd;
 }
 

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

@@ -0,0 +1,105 @@
+/**
+ * seedAgentPersonas.test.cjs — unit tests for src/main/seedAgentPersonas.cjs.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/seedAgentPersonas.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeEach, afterEach } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+let tmpHome;
+let realHome;
+let seedAgentPersonas;
+
+// config.cjs bakes os.homedir() into top-level consts at first require
+// (allowedRoots/WRITE_PREFIXES, used by writeJsonSync) — must be purged
+// alongside seedAgentPersonas.cjs so each test's tmpHome takes effect.
+const MODULES_TO_RELOAD = ['../seedAgentPersonas.cjs', '../config.cjs'];
+
+function purgeRequireCache() {
+  for (const m of MODULES_TO_RELOAD) {
+    try { delete require.cache[require.resolve(m)]; } catch { /* not loaded yet */ }
+  }
+}
+
+beforeEach(() => {
+  realHome = process.env.HOME;
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'seed-agent-personas-test-'));
+  process.env.HOME = tmpHome;
+  delete process.env.SM_SEED_AGENT_PERSONAS_DISABLE;
+  purgeRequireCache();
+  ({ seedAgentPersonas } = require('../seedAgentPersonas.cjs'));
+});
+
+afterEach(() => {
+  process.env.HOME = realHome;
+  delete process.env.SM_SEED_AGENT_PERSONAS_DISABLE;
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+  purgeRequireCache();
+});
+
+function agentsDir() {
+  return path.join(tmpHome, '.claude', 'agents');
+}
+
+function markerPath() {
+  return path.join(tmpHome, '.claude', 'session-manager', '.agent-personas-seeded');
+}
+
+function silentLogger() {
+  return { log: () => {}, warn: () => {} };
+}
+
+test('fresh seed writes both persona files', async () => {
+  await seedAgentPersonas({ logger: silentLogger() });
+
+  const architect = path.join(agentsDir(), 'architect.md');
+  const devLead = path.join(agentsDir(), 'dev-lead.md');
+  expect(fs.existsSync(architect)).toBe(true);
+  expect(fs.existsSync(devLead)).toBe(true);
+
+  const bundledArchitect = fs.readFileSync(
+    path.join(__dirname, '..', '..', 'seed', 'agents', 'architect.md'),
+    'utf8'
+  );
+  expect(fs.readFileSync(architect, 'utf8')).toBe(bundledArchitect);
+
+  const marker = JSON.parse(fs.readFileSync(markerPath(), 'utf8'));
+  expect(marker.done).toBe(true);
+});
+
+test('a pre-existing persona file is left byte-identical', async () => {
+  fs.mkdirSync(agentsDir(), { recursive: true });
+  const architect = path.join(agentsDir(), 'architect.md');
+  const customContent = '# My custom architect\nnever overwrite me\n';
+  fs.writeFileSync(architect, customContent);
+
+  await seedAgentPersonas({ logger: silentLogger() });
+
+  expect(fs.readFileSync(architect, 'utf8')).toBe(customContent);
+  // dev-lead had no pre-existing file, so it should still be seeded.
+  expect(fs.existsSync(path.join(agentsDir(), 'dev-lead.md'))).toBe(true);
+});
+
+test('done:true marker short-circuits without touching agents dir', async () => {
+  const mPath = markerPath();
+  fs.mkdirSync(path.dirname(mPath), { recursive: true });
+  fs.writeFileSync(mPath, JSON.stringify({ done: true, attempts: 1, ts: '2026-01-01T00:00:00.000Z' }));
+
+  await seedAgentPersonas({ logger: silentLogger() });
+
+  expect(fs.existsSync(agentsDir())).toBe(false);
+});
+
+test('SM_SEED_AGENT_PERSONAS_DISABLE=1 short-circuits', async () => {
+  process.env.SM_SEED_AGENT_PERSONAS_DISABLE = '1';
+
+  await seedAgentPersonas({ logger: silentLogger() });
+
+  expect(fs.existsSync(agentsDir())).toBe(false);
+  expect(fs.existsSync(markerPath())).toBe(false);
+});

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

@@ -0,0 +1,145 @@
+/**
+ * seedSchedulerMcp.test.cjs — unit tests for src/main/seedSchedulerMcp.cjs.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/seedSchedulerMcp.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeEach, afterEach } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+let tmpHome;
+let realHome;
+let seedSchedulerMcp;
+
+// config.cjs bakes os.homedir() into top-level consts at first require
+// (allowedRoots/WRITE_PREFIXES, used by writeJsonSync) — must be purged
+// alongside seedSchedulerMcp.cjs so each test's tmpHome takes effect.
+const MODULES_TO_RELOAD = ['../seedSchedulerMcp.cjs', '../config.cjs'];
+
+function purgeRequireCache() {
+  for (const m of MODULES_TO_RELOAD) {
+    try { delete require.cache[require.resolve(m)]; } catch { /* not loaded yet */ }
+  }
+}
+
+beforeEach(() => {
+  realHome = process.env.HOME;
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'seed-scheduler-mcp-test-'));
+  process.env.HOME = tmpHome;
+  delete process.env.SM_SEED_SCHEDULER_MCP_DISABLE;
+  purgeRequireCache();
+  ({ seedSchedulerMcp } = require('../seedSchedulerMcp.cjs'));
+});
+
+afterEach(() => {
+  process.env.HOME = realHome;
+  delete process.env.SM_SEED_SCHEDULER_MCP_DISABLE;
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+  purgeRequireCache();
+});
+
+function markerPath() {
+  return path.join(tmpHome, '.claude', 'session-manager', '.scheduler-mcp-seeded');
+}
+
+function claudeJsonPath() {
+  return path.join(tmpHome, '.claude.json');
+}
+
+function silentLogger() {
+  return { log: () => {}, warn: () => {} };
+}
+
+function readMarker() {
+  return JSON.parse(fs.readFileSync(markerPath(), 'utf8'));
+}
+
+test('fresh registration calls addFn with the absolute server path and writes done marker', async () => {
+  const calls = [];
+  const addFn = async (serverPath) => {
+    calls.push(serverPath);
+    return { ok: true, exitCode: 0 };
+  };
+
+  await seedSchedulerMcp({ logger: silentLogger(), addFn });
+
+  expect(calls).toHaveLength(1);
+  expect(path.isAbsolute(calls[0])).toBe(true);
+  expect(calls[0].endsWith(path.join('scripts', 'scheduler-mcp-server.cjs'))).toBe(true);
+
+  const marker = readMarker();
+  expect(marker.done).toBe(true);
+  expect(marker.attempts).toBe(0);
+});
+
+test('already-registered at user scope short-circuits without calling addFn', async () => {
+  fs.writeFileSync(
+    claudeJsonPath(),
+    JSON.stringify({
+      mcpServers: {
+        'session-manager-scheduler': { type: 'stdio', command: 'node', args: ['/some/path/scheduler-mcp-server.cjs'] },
+        fetch: { type: 'stdio', command: 'uvx', args: ['mcp-server-fetch'] },
+      },
+    })
+  );
+  let called = false;
+  const addFn = async () => { called = true; return { ok: true }; };
+
+  await seedSchedulerMcp({ logger: silentLogger(), addFn });
+
+  expect(called).toBe(false);
+  const marker = readMarker();
+  expect(marker.done).toBe(true);
+
+  // Untouched — the pre-existing registration (and sibling entries) stay as-is.
+  const claudeJson = JSON.parse(fs.readFileSync(claudeJsonPath(), 'utf8'));
+  expect(claudeJson.mcpServers['session-manager-scheduler'].args).toEqual(['/some/path/scheduler-mcp-server.cjs']);
+  expect(claudeJson.mcpServers.fetch).toBeDefined();
+});
+
+test('done:true marker short-circuits without calling addFn', async () => {
+  fs.mkdirSync(path.dirname(markerPath()), { recursive: true });
+  fs.writeFileSync(markerPath(), JSON.stringify({ done: true, attempts: 1, ts: '2026-01-01T00:00:00.000Z' }));
+  let called = false;
+  const addFn = async () => { called = true; return { ok: true }; };
+
+  await seedSchedulerMcp({ logger: silentLogger(), addFn });
+
+  expect(called).toBe(false);
+});
+
+test('SM_SEED_SCHEDULER_MCP_DISABLE=1 short-circuits', async () => {
+  process.env.SM_SEED_SCHEDULER_MCP_DISABLE = '1';
+  let called = false;
+  const addFn = async () => { called = true; return { ok: true }; };
+
+  await seedSchedulerMcp({ logger: silentLogger(), addFn });
+
+  expect(called).toBe(false);
+  expect(fs.existsSync(markerPath())).toBe(false);
+});
+
+test('a failed attempt bumps the counter and stops after MAX_ATTEMPTS', async () => {
+  const addFn = async () => ({ ok: false, error: 'boom' });
+
+  await seedSchedulerMcp({ logger: silentLogger(), addFn });
+  expect(readMarker()).toMatchObject({ done: false, attempts: 1 });
+
+  await seedSchedulerMcp({ logger: silentLogger(), addFn });
+  expect(readMarker()).toMatchObject({ done: false, attempts: 2 });
+
+  await seedSchedulerMcp({ logger: silentLogger(), addFn });
+  expect(readMarker()).toMatchObject({ done: false, attempts: 3 });
+
+  // MAX_ATTEMPTS reached — a 4th run must not call addFn again or bump further.
+  let called = false;
+  const trackedAddFn = async () => { called = true; return { ok: false, error: 'boom' }; };
+  await seedSchedulerMcp({ logger: silentLogger(), addFn: trackedAddFn });
+
+  expect(called).toBe(false);
+  expect(readMarker()).toMatchObject({ done: false, attempts: 3 });
+});

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

@@ -0,0 +1,100 @@
+/**
+ * seedStatus.test.cjs — unit tests for src/main/seedStatus.cjs.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/seedStatus.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeEach, afterEach } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+let tmpHome;
+let realHome;
+let getSeedStatus;
+
+// config.cjs (via seedSchedulerMcp/seedAgentPersonas) and each seed*.cjs
+// module bake os.homedir() into top-level consts at first require — purge
+// all of them alongside seedStatus.cjs so each test's tmpHome takes effect.
+const MODULES_TO_RELOAD = [
+  '../seedStatus.cjs',
+  '../seedDevPlugin.cjs',
+  '../seedSchedulerMcp.cjs',
+  '../seedAgentPersonas.cjs',
+  '../config.cjs',
+];
+
+function purgeRequireCache() {
+  for (const m of MODULES_TO_RELOAD) {
+    try { delete require.cache[require.resolve(m)]; } catch { /* not loaded yet */ }
+  }
+}
+
+beforeEach(() => {
+  realHome = process.env.HOME;
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'seed-status-test-'));
+  process.env.HOME = tmpHome;
+  purgeRequireCache();
+  ({ getSeedStatus } = require('../seedStatus.cjs'));
+});
+
+afterEach(() => {
+  process.env.HOME = realHome;
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+  purgeRequireCache();
+});
+
+const MARKER_NAMES = {
+  'dev-plugin': '.dev-plugin-seeded',
+  'scheduler-mcp': '.scheduler-mcp-seeded',
+  'agent-personas': '.agent-personas-seeded',
+};
+
+function markerPath(id) {
+  return path.join(tmpHome, '.claude', 'session-manager', MARKER_NAMES[id]);
+}
+
+function writeMarker(id, contents) {
+  const p = markerPath(id);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, contents);
+}
+
+test('no marker files at all → every seeder reports pending with a fix string', () => {
+  const status = getSeedStatus();
+  for (const id of Object.keys(MARKER_NAMES)) {
+    expect(status[id].status).toBe('pending');
+    expect(typeof status[id].fix).toBe('string');
+    expect(status[id].fix.length).toBeGreaterThan(0);
+  }
+});
+
+for (const id of Object.keys(MARKER_NAMES)) {
+  test(`${id}: done:true marker → done`, () => {
+    writeMarker(id, JSON.stringify({ done: true, attempts: 1, ts: '2026-01-01T00:00:00.000Z' }));
+    expect(getSeedStatus()[id].status).toBe('done');
+  });
+
+  test(`${id}: done:false, attempts below max → pending`, () => {
+    writeMarker(id, JSON.stringify({ done: false, attempts: 1, ts: '2026-01-01T00:00:00.000Z' }));
+    expect(getSeedStatus()[id].status).toBe('pending');
+  });
+
+  test(`${id}: done:false, attempts >= max → exhausted`, () => {
+    writeMarker(id, JSON.stringify({ done: false, attempts: 3, ts: '2026-01-01T00:00:00.000Z' }));
+    expect(getSeedStatus()[id].status).toBe('exhausted');
+  });
+
+  test(`${id}: unparseable marker → pending, never throws`, () => {
+    writeMarker(id, 'not json at all {{{');
+    expect(() => getSeedStatus()).not.toThrow();
+    expect(getSeedStatus()[id].status).toBe('pending');
+  });
+
+  test(`${id}: missing marker file → pending`, () => {
+    // No file written for this id — directory may not even exist.
+    expect(getSeedStatus()[id].status).toBe('pending');
+  });
+}

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

@@ -0,0 +1,89 @@
+/**
+ * workTypeLibrary.test.cjs — cross-file consistency tests for the WorkType
+ * union. Epic tag and PRD tag are one concept (WorkType); this test enforces
+ * that every declaration site agrees, since the two module systems involved
+ * (renderer .ts, main .cjs, and the preload .d.ts that can import neither)
+ * can't enforce it via a shared import. Modelled on scheduleJobSchema.test.cjs's
+ * JOB_STATUSES cross-file assertions.
+ *
+ * Run: timeout 300 npx vitest run src/main/__tests__/workTypeLibrary.test.cjs
+ */
+
+'use strict';
+
+import { test, expect } from 'vitest';
+const fs = require('node:fs');
+const path = require('node:path');
+const { WORK_TYPES, WorkTypeSchema } = require('../lib/workTypeLibrary.cjs');
+
+const REPO_ROOT = path.resolve(__dirname, '../../..');
+const TAG_LIBRARY_PATH = path.join(REPO_ROOT, 'src/renderer/lib/tagLibrary.ts');
+const API_D_TS_PATH = path.join(REPO_ROOT, 'src/preload/api.d.ts');
+const IPC_SCHEMAS_PATH = path.join(REPO_ROOT, 'src/main/ipcSchemas.cjs');
+const SCHEDULER_MCP_SERVER_PATH = path.join(REPO_ROOT, 'scripts/scheduler-mcp-server.cjs');
+
+test('WORK_TYPES matches the expected 6 canonical ids in order', () => {
+  expect(WORK_TYPES).toEqual([
+    'feature',
+    'bug',
+    'discussion',
+    'build',
+    'project-home-builder',
+    'bilko-host-publisher',
+  ]);
+});
+
+test('WorkTypeSchema accepts every WORK_TYPES value and rejects an unknown one', () => {
+  for (const value of WORK_TYPES) {
+    expect(WorkTypeSchema.safeParse(value).success).toBe(true);
+  }
+  expect(WorkTypeSchema.safeParse('not-a-real-tag').success).toBe(false);
+});
+
+test('WORK_TYPES matches the tag ids declared in tagLibrary.ts TAG_LIBRARY, in order', () => {
+  const src = fs.readFileSync(TAG_LIBRARY_PATH, 'utf8');
+  const tagMatches = [...src.matchAll(/^\s*tag:\s*'([^']+)',/gm)].map((m) => m[1]);
+  expect(tagMatches).toEqual(WORK_TYPES);
+});
+
+test('api.d.ts tag unions (line ~1166 and ~1687) both contain exactly the same 6 values', () => {
+  const src = fs.readFileSync(API_D_TS_PATH, 'utf8');
+  const unionMatches = [...src.matchAll(/tag\?:\s*((?:'[^']+'\s*\|?\s*)+);/g)].map((m) =>
+    m[1]
+      .split('|')
+      .map((s) => s.trim().replace(/^'|'$/g, ''))
+      .filter(Boolean)
+  );
+
+  expect(unionMatches.length).toBeGreaterThanOrEqual(2);
+  for (const union of unionMatches) {
+    expect(union).toEqual(WORK_TYPES);
+  }
+});
+
+test('ipcSchemas.cjs no longer hardcodes the full-taxonomy tag z.enum literal', () => {
+  const src = fs.readFileSync(IPC_SCHEMAS_PATH, 'utf8');
+  // The old scheduleRetagPrd literal was missing 'bilko-host-publisher'
+  // (5 of the 6 WORK_TYPES values) — assert that exact stale shape is gone.
+  expect(src).not.toMatch(/z\.enum\(\['feature',\s*'bug',\s*'discussion',\s*'build',\s*'project-home-builder'\]\)/);
+  // Epic tag (schedulerCreateEpic-style routes) draws on the full 6-value
+  // WorkType union via EpicTagSchema, which is itself WorkTypeSchema
+  // (promptSessionSchema.cjs). PRD tag fields (schedulerCreatePrd,
+  // adminPrdFrontmatterPatch) draw on the narrower 5-value PrdWorkTypeSchema
+  // — independent values, same shared vocabulary (PRD 1041).
+  expect(src).toMatch(/tag:\s*EpicTagSchema/);
+  const prdTagMatches = [...src.matchAll(/tag:\s*PrdWorkTypeSchema/g)];
+  expect(prdTagMatches.length).toBeGreaterThanOrEqual(2);
+});
+
+test('scheduler-mcp-server.cjs requires PRD_WORK_TYPES rather than hardcoding a tag enum literal, and imports it exactly twice (scheduler_create_prd + scheduler_update_prd)', () => {
+  const { PRD_WORK_TYPES } = require('../lib/workTypeLibrary.cjs');
+  const src = fs.readFileSync(SCHEDULER_MCP_SERVER_PATH, 'utf8');
+  expect(src).toMatch(/require\(['"].*workTypeLibrary\.cjs['"]\)/);
+  const occurrences = [...src.matchAll(/enum:\s*PRD_WORK_TYPES/g)].length;
+  // scheduler_create_prd's inputSchema.tag.enum and scheduler_update_prd's
+  // frontmatter.tag.enum — exactly 2 sites, not the Epic-tag (6-value)
+  // enum on feedback_open_session's tag property.
+  expect(occurrences).toBe(2);
+  expect(PRD_WORK_TYPES).toEqual(['feature', 'bug', 'build', 'project-home-builder', 'bilko-host-publisher']);
+});

package/src/main/agentLibrary.cjs

@@ -22,6 +22,7 @@ const fsSync = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
 const { splitFrontmatter } = require('./lib/prdFrontmatter.cjs');
+const { resolvePersonaPaths } = require('./lib/epicMint.cjs');
 const configMgr = require('./config.cjs');
 const sessionsStore = require('./sessionsStore.cjs');
 
@@ -249,6 +250,47 @@ async function listPersonas({
   return personas;
 }
 
+/**
+ * Reads a persona `.md` file's raw text for `epicIntake.ts`'s `agentBody`
+ * input, honoring the same project-overlay-then-global precedence as
+ * `epicMint.cjs`'s `resolvePersonaPaths` (a project's `<cwd>/.claude/agents/
+ * <name>.md` wins over `~/.claude/agents/<name>.md`) — the same precedence
+ * `listPersonas` deliberately does NOT apply, since that lists only the
+ * global directory for the Agent Library nav page. Returns `null` when
+ * neither location has the file; frontmatter stripping and the 6000-char cap
+ * are epicIntake.ts's job, not this reader's.
+ */
+async function getPersonaBody({
+  cwd,
+  name,
+  validatePath = configMgr.validatePath,
+} = {}) {
+  // Same gate savePersona/deletePersona apply before touching a path built
+  // from `name` (agentLibrary.cjs's PERSONA_NAME_RE check) — without it a
+  // `name` like "../../other-project/CLAUDE" survives resolvePersonaPaths'
+  // plain path.join and validatePath's allowed-roots check (which only
+  // confirms the resolved path stays under the home dir / an opened
+  // project), letting any readable .md under those roots be read and
+  // forwarded into the Epic's opening prompt.
+  if (!PERSONA_NAME_RE.test(name || '')) return null;
+  const { projectPath, globalPath } = resolvePersonaPaths(cwd, name);
+  for (const candidate of [projectPath, globalPath]) {
+    let real;
+    try {
+      real = validatePath(candidate);
+    } catch {
+      continue;
+    }
+    try {
+      const text = await fsp.readFile(real, 'utf8');
+      return { path: real, text };
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
 module.exports = {
   listPersonas,
   openProjects,
@@ -257,6 +299,7 @@ module.exports = {
   deletePersona,
   removeOverride,
   serializePersona,
+  getPersonaBody,
   PERSONA_NAME_RE,
   ALL_PROJECTS,
 };

package/src/main/health.cjs

@@ -181,6 +181,37 @@ function evaluatePerProjectStall(stallSummary, lastRunAtIso, now, thresholdMs) {
   return results;
 }
 
+// Parses the "SIZE BUDGET — 12,000 chars" header line out of a project's
+// CLAUDE.md text. Tolerant of the em-dash, bold markers, the leading
+// blockquote '>', and the thousands comma. Returns null (not a throw, not a
+// default) when the line is absent or unparseable — a CLAUDE.md that
+// predates this convention has nothing to enforce, and that must stay a
+// silent skip rather than a manufactured RED.
+function parseClaudeMdBudget(text) {
+  if (typeof text !== 'string') return null;
+  const match = text.match(/SIZE BUDGET\s*[—-]+\s*([\d,]+)\s*chars/i);
+  if (!match) return null;
+  const n = Number(match[1].replace(/,/g, ''));
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+// Pure comparison of CLAUDE.md's actual byte size against its self-declared
+// budget (see parseClaudeMdBudget). budget === null means "no budget
+// declared" — skip silently rather than treating it as 0 or infinite.
+function evaluateClaudeMdBudget(chars, budget) {
+  if (budget == null) return { ok: true, applicable: false };
+  const overage = chars - budget;
+  if (overage <= 0) return { ok: true, applicable: true, chars, budget };
+  return {
+    ok: false,
+    applicable: true,
+    chars,
+    budget,
+    overage,
+    message: `CLAUDE.md is ${chars} chars, over its ${budget}-char budget by ${overage} (see the SIZE BUDGET note in CLAUDE.md)`,
+  };
+}
+
 // Pure evaluator over migratePrds()'s { moved, skipped, unresolved } result —
 // kept separate from the fs-touching check() call site so it's directly
 // unit-testable, matching evaluateTickLiveness's pattern.
@@ -443,6 +474,23 @@ async function check() {
     };
   }
 
+  // 6.4. Check project CLAUDE.md against its own self-declared SIZE BUDGET
+  // header (see the CLAUDE.md size-budget note). Skips silently when no
+  // budget line is present — this is not required for every project.
+  try {
+    const claudeMdPath = path.join(PROJECT_ROOT, 'CLAUDE.md');
+    const claudeMdText = fs.readFileSync(claudeMdPath, 'utf8');
+    const chars = Buffer.byteLength(claudeMdText, 'utf8');
+    const budget = parseClaudeMdBudget(claudeMdText);
+    const budgetResult = evaluateClaudeMdBudget(chars, budget);
+    status.components.claude_md_budget = budgetResult;
+    if (!budgetResult.ok) {
+      status.issues.push(budgetResult.message);
+    }
+  } catch (e) {
+    status.components.claude_md_budget = { ok: true, applicable: false };
+  }
+
   // 6.5. Check ~/.claude/CLAUDE.md's @import chain resolves cleanly.
   // Informational only — a broken/stale persona import degrades instruction
   // fidelity, not app health, so it never flips status.ok to false. See
@@ -492,7 +540,7 @@ async function check() {
   // Critical: nodejs, config dir, typescript, build artifact, test infrastructure.
   // Non-fatal: scheduler/transcripts dirs may not exist on fresh install.
   // Informational: app log age (shows if app is running, but not blocking).
-  const criticalComponents = ['nodejs', 'config_dir', 'typescript', 'build_artifact', 'test_infrastructure', 'scheduler_queue', 'prd_migration'];
+  const criticalComponents = ['nodejs', 'config_dir', 'typescript', 'build_artifact', 'test_infrastructure', 'scheduler_queue', 'prd_migration', 'claude_md_budget'];
   status.ok = criticalComponents.every((c) => status.components[c]?.ok !== false);
 
   status.elapsedMs = Date.now() - start;
@@ -515,6 +563,8 @@ module.exports = {
   evaluatePrdMigrationHealth,
   computeProjectProblemCounts,
   evaluatePerProjectStall,
+  parseClaudeMdBudget,
+  evaluateClaudeMdBudget,
   TICK_STALL_THRESHOLD_MS,
   HEARTBEAT_STALE_MS,
 };