claude-code-session-manager 0.73.2 → 0.74.0

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,
 };

package/src/main/index.cjs

@@ -466,11 +466,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();

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;
@@ -962,6 +973,7 @@ module.exports = {
     chatClassifyTicket,
     chatExternalSend,
     exchangesList,
+    agentsSavePersona,
   },
   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/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 {

package/src/main/lib/agentPersonaSchema.cjs

@@ -0,0 +1,82 @@
+/**
+ * Canonical runtime schema for an Agent persona WRITE payload, mirroring the
+ * TS `AgentPersonaSaveInput` interface at src/preload/api.d.ts:229-246
+ * field-for-field.
+ *
+ * Modelled on promptSessionSchema.cjs / scheduleJobSchema.cjs's "zod schema
+ * asserted at the main-process boundary" pattern: Epic and Job each got this
+ * guarantee only after a production incident (see scheduleJobSchema.cjs's
+ * header for the Job one). Agent is the third ERD entity
+ * (Agent/WorkType/Epic/PRD/Job) and, until this schema, the only one with
+ * zero validation between the renderer and disk — `savePersona`
+ * (agentLibrary.cjs) checked only that `name` was kebab-case.
+ *
+ * This schema covers the WRITE path only (`agents.savePersona`). The READ
+ * path (`listPersonas`) stays permissive on purpose — personas on disk may be
+ * hand-written or authored by Claude Code itself and must keep loading even
+ * if they carry fields this app doesn't recognize.
+ *
+ * Plain CJS, no Electron dependency, so it's requirable from ipcSchemas.cjs
+ * the same way promptSessionSchema.cjs and scheduleJobSchema.cjs already are.
+ */
+'use strict';
+
+const { z } = require('zod');
+const { WorkTypeSchema } = require('./workTypeLibrary.cjs');
+const { PERSONA_NAME_RE, ALL_PROJECTS } = require('../agentLibrary.cjs');
+
+// Bounded free-text fields — generous for legitimate persona authoring while
+// still blocking a renderer from writing an effectively-unbounded frontmatter
+// value (mirrors ipcSchemas.cjs's title/description caps elsewhere).
+const PersonaNameSchema = z.string().regex(PERSONA_NAME_RE, 'agent name must be lowercase, hyphenated (e.g. "my-agent")');
+const BoundedString = z.string().max(2000);
+
+// `projects` entries are either the `'*'` sentinel (every project) or an
+// absolute path — agentLibrary.cjs's openProjects always deals in absolute
+// cwds, and a relative entry could never match one.
+const ProjectEntrySchema = z.string().refine(
+  (v) => v === ALL_PROJECTS || v.startsWith('/'),
+  `must be "${ALL_PROJECTS}" or an absolute path`,
+);
+
+// Mirrors AgentPersonaSaveInput (src/preload/api.d.ts:229-246). `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.
+const AgentPersonaSaveSchema = z.object({
+  name: PersonaNameSchema,
+  // Previous filename, when renaming an existing persona. Omit when creating.
+  originalName: PersonaNameSchema.optional(),
+  description: BoundedString,
+  tools: z.array(BoundedString),
+  model: BoundedString,
+  color: BoundedString,
+  tags: z.array(WorkTypeSchema),
+  projects: z.array(ProjectEntrySchema).optional(),
+  action: z.string().max(20000).optional(),
+  actionLabel: BoundedString.optional(),
+  title: BoundedString.optional(),
+  // Unbounded — a persona's body is arbitrary system-prompt prose.
+  body: z.string(),
+});
+
+/**
+ * Throws a clear, descriptive error (not a raw ZodError dump) when `persona`
+ * doesn't match AgentPersonaSaveSchema. Mirrors assertValidPromptSession /
+ * assertValidScheduleJob's shape and message format exactly.
+ */
+function assertValidAgentPersonaSave(persona) {
+  const result = AgentPersonaSaveSchema.safeParse(persona);
+  if (!result.success) {
+    const issues = result.error.issues
+      .map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`)
+      .join('; ');
+    throw new Error(`assertValidAgentPersonaSave: invalid AgentPersonaSave shape — ${issues}`);
+  }
+  return result.data;
+}
+
+module.exports = {
+  AgentPersonaSaveSchema,
+  assertValidAgentPersonaSave,
+};

package/src/main/lib/epicMint.cjs

@@ -28,6 +28,7 @@
 'use strict';
 
 const fs = require('node:fs');
+const os = require('node:os');
 const path = require('node:path');
 const crypto = require('node:crypto');
 const { resolveEpicPrdWriteDir } = require('./prdLocations.cjs');
@@ -117,6 +118,59 @@ function hasOwn(obj, key) {
   return Object.prototype.hasOwnProperty.call(obj, key);
 }
 
+/**
+ * safeAgentMdPath(baseDir, agentType) — `<baseDir>/<agentType>.md`, refused
+ * (returns null) if resolving it would escape baseDir (a `..`-laced
+ * agentType). Deliberately NOT config.cjs's validatePath: that guards
+ * allowedRoots (home dir + every cwd a TAB has opened), a registry ensureEpic
+ * cannot assume the caller's cwd is already in — epicMint.cjs is a plain
+ * Node module callable from scheduler/watchdog contexts with a trusted cwd
+ * that was never opened as a TAB. Containment within baseDir is the only
+ * property that actually matters here.
+ */
+function safeAgentMdPath(baseDir, agentType) {
+  const resolvedBase = path.resolve(baseDir);
+  const withSep = resolvedBase.endsWith(path.sep) ? resolvedBase : resolvedBase + path.sep;
+  const resolved = path.resolve(resolvedBase, `${agentType}.md`);
+  return resolved.startsWith(withSep) ? resolved : null;
+}
+
+/**
+ * resolvePersonaPaths(cwd, agentType, deps) — the two on-disk locations an
+ * agentType name could resolve to, project overlay first: matches the
+ * precedence agentLibrary.cjs already documents (a project overlay at
+ * `<cwd>/.claude/agents/<name>.md` wins over the global
+ * `~/.claude/agents/<name>.md`).
+ */
+function resolvePersonaPaths(cwd, agentType, deps = {}) {
+  const projectDir = deps.projectDir || path.join(cwd, '.claude', 'agents');
+  const globalDir = deps.globalDir || path.join(os.homedir(), '.claude', 'agents');
+  return {
+    projectPath: path.join(projectDir, `${agentType}.md`),
+    globalPath: path.join(globalDir, `${agentType}.md`),
+  };
+}
+
+/**
+ * personaFileExists(cwd, agentType, deps) — true iff `agentType` resolves to
+ * a readable `.md` persona file, checking the project overlay before the
+ * global agents dir. Never throws (a traversal attempt or missing file is
+ * treated as "doesn't exist", same fail-closed spirit as
+ * agentModelResolve.cjs's readPersonaModel).
+ */
+function personaFileExists(cwd, agentType, deps = {}) {
+  const projectDir = deps.projectDir || path.join(cwd, '.claude', 'agents');
+  const globalDir = deps.globalDir || path.join(os.homedir(), '.claude', 'agents');
+  for (const baseDir of [projectDir, globalDir]) {
+    const real = safeAgentMdPath(baseDir, agentType);
+    if (!real) continue;
+    try {
+      if (fs.statSync(real).isFile()) return true;
+    } catch { /* not found or unreadable — keep checking */ }
+  }
+  return false;
+}
+
 function slugify(text) {
   return String(text || 'epic')
     .toLowerCase()
@@ -168,7 +222,7 @@ function withPathLock(lockPath, task) {
  * The Epic's id doubles as its directory name under scheduler/epics/, so the
  * PromptSession ↔ on-disk Epic mapping is 1:1 with no lookup table.
  */
-function ensureEpic(cwd, { goalText, tag, epicId: explicitEpicId, status = 'proposed', openingPrompt = null, sections = null, source = null, agentType = null, mintAuthority = null } = {}) {
+function ensureEpic(cwd, { goalText, tag, epicId: explicitEpicId, status = 'proposed', openingPrompt = null, sections = null, source = null, agentType = null, mintAuthority = null } = {}, deps = {}) {
   if (!cwd || typeof cwd !== 'string') throw new Error('ensureEpic: cwd is required');
   // A relative cwd (e.g. a caller passing '.') would otherwise get stored
   // verbatim on the minted Epic's `cwd` field — the renderer's EpicsWorkspace
@@ -229,6 +283,23 @@ function ensureEpic(cwd, { goalText, tag, epicId: explicitEpicId, status = 'prop
       throw new Error(reason);
     }
 
+    // WRITE-TIME FK CHECK (throw on write, report on read — see this file's
+    // header + agentModelResolve.cjs's readPersonaModel, which is the READ
+    // side of this same FK and stays permissive on purpose). A mint whose
+    // agentType names a persona that doesn't resolve is a bug in the caller
+    // (a typo, or a persona deleted between the picker loading and the mint
+    // landing) — refuse it now rather than silently orphaning the Epic.
+    if (agentType) {
+      const checkPersonaExists = deps.personaExists || personaFileExists;
+      if (!checkPersonaExists(cwd, agentType, deps)) {
+        const { projectPath, globalPath } = resolvePersonaPaths(cwd, agentType, deps);
+        const reason = `agentType '${agentType}' does not resolve to a readable persona file — checked `
+          + `${projectPath} and ${globalPath}`;
+        appendAuditEvent('epic_mint_refused', { cwd, epicId: explicitEpicId ?? null, status, reason });
+        throw new Error(`ensureEpic: ${reason}`);
+      }
+    }
+
     const epicId = `${slugify(goalText)}-${crypto.randomUUID().slice(0, 8)}`;
     const now = new Date().toISOString();
     const session = {
@@ -358,6 +429,8 @@ module.exports = {
   removeEpic,
   activeIndexPath,
   readActiveIndex,
+  personaFileExists,
+  resolvePersonaPaths,
   // Exported so lib/activeIndexMerge.cjs's renderer-facing merge IPC handler
   // serializes through the SAME lock instance as ensureEpic/
   // appendPrdCreatedEvent (module-level Map, shared via Node's require

package/src/main/lib/prdFrontmatter.cjs

@@ -23,6 +23,10 @@
  */
 'use strict';
 
+const { PRD_WORK_TYPES } = require('./workTypeLibrary.cjs');
+
+const PRD_TAG_VALUES = new Set(PRD_WORK_TYPES);
+
 function splitFrontmatter(raw) {
   if (typeof raw !== 'string' || !raw.startsWith('---\n')) {
     return { fm: {}, body: raw, fmLineCount: 0 };
@@ -118,11 +122,8 @@ function applyKey(fm, key, after) {
       fm.sourceTabId = String(v);
       return;
     case 'tag':
-      // Matches the TS source's applyKey exactly: a 'discussion'-tagged
-      // ticket never reaches PRD authoring, so that value is never parsed
-      // here even if present in a hand-edited file — see this file's header
-      // comment.
-      if (v === 'feature' || v === 'bug' || v === 'build') fm.tag = v;
+      // Matches the TS source's applyKey exactly — see PRD_TAG_VALUES above.
+      if (PRD_TAG_VALUES.has(v)) fm.tag = v;
       return;
     case 'createdVia':
       fm.createdVia = String(v);

package/src/main/lib/promptSessionSchema.cjs

@@ -13,22 +13,14 @@
 'use strict';
 
 const { z } = require('zod');
+const { WorkTypeSchema } = require('./workTypeLibrary.cjs');
 
 // Mirrors EpicTag (src/renderer/lib/tagLibrary.ts:10) — the Epic-level
-// mission tag, NOT the same value set as ipcSchemas.cjs's scheduleRetagPrd
-// tag enum (~line 349), which only covers 5 of these 6 values ('feature',
-// 'bug', 'discussion', 'build', 'project-home-builder') and is missing
-// 'bilko-host-publisher' — the two enums describe related but distinct
-// concepts (PRD-scheduling tag vs. Epic-mission tag), so this is its own
-// definition rather than an import of that one.
-const EpicTagSchema = z.enum([
-  'feature',
-  'bug',
-  'discussion',
-  'build',
-  'project-home-builder',
-  'bilko-host-publisher',
-]);
+// mission tag. Epic tag and PRD tag (ipcSchemas.cjs's scheduleRetagPrd `tag`
+// field) are the same WorkType concept, so both validate against the shared
+// WorkTypeSchema from workTypeLibrary.cjs rather than each declaring their
+// own enum literal.
+const EpicTagSchema = WorkTypeSchema;
 
 // Mirrors EpicSource (src/renderer/state/promptSessions.ts:22-27).
 const EpicSourceSchema = z.object({

package/src/main/lib/workTypeLibrary.cjs

@@ -0,0 +1,48 @@
+/**
+ * Single source of truth for the WorkType id list — the Epic-mission tag
+ * (`PromptSession['tag']`, src/renderer/state/promptSessions.ts) and the PRD
+ * tag (`scheduleRetagPrd`'s `tag` field, ipcSchemas.cjs) are ONE concept, not
+ * two: a domain decision confirmed by the project owner. Both now validate
+ * against this same enum.
+ *
+ * `WORK_TYPES` mirrors the tag ids in src/renderer/lib/tagLibrary.ts's
+ * `TAG_LIBRARY`, in the same order — that file stays the human-facing SoT for
+ * labels/descriptions/developEagerness; this one is only the id list + zod
+ * enum, kept in sync with tagLibrary.ts by
+ * src/main/__tests__/workTypeLibrary.test.cjs (tagLibrary.ts is a renderer
+ * .ts module main-process .cjs can't import — see CLAUDE.md "no CommonJS in
+ * renderer, no ES modules in main").
+ *
+ * Plain CJS, no Electron dependency, so it's requirable from scheduler/CLI
+ * contexts — same constraint promptSessionSchema.cjs and scheduleJobSchema.cjs
+ * already satisfy.
+ */
+'use strict';
+
+const { z } = require('zod');
+
+const WORK_TYPES = Object.freeze([
+  'feature',
+  'bug',
+  'discussion',
+  'build',
+  'project-home-builder',
+  'bilko-host-publisher',
+]);
+
+const WorkTypeSchema = z.enum(WORK_TYPES);
+
+// A 'discussion'-tagged ticket never reaches PRD authoring (a domain
+// invariant unrelated to the Epic/PRD tag unification above), so the PRD
+// frontmatter `tag` field — parsed in prdFrontmatter.cjs/.ts and patched via
+// ipcSchemas.cjs's adminPrdFrontmatterPatch — excludes it even though
+// WorkTypeSchema itself (used at PRD-create time) does not.
+const PRD_WORK_TYPES = Object.freeze(WORK_TYPES.filter((t) => t !== 'discussion'));
+const PrdWorkTypeSchema = z.enum(PRD_WORK_TYPES);
+
+module.exports = {
+  WORK_TYPES,
+  WorkTypeSchema,
+  PRD_WORK_TYPES,
+  PrdWorkTypeSchema,
+};

package/src/preload/api.d.ts

@@ -199,6 +199,11 @@ export interface McpStatusResult {
   checkedAt: number;
 }
 
+/** Mirrors WorkType (src/main/lib/workTypeLibrary.cjs) / EpicTag (tagLibrary.ts) — the
+ *  same Epic-mission taxonomy, reused here since an Agent persona's `tags` field is that
+ *  same concept, not a free-form string list. */
+export type AgentPersonaTag = 'feature' | 'bug' | 'discussion' | 'build' | 'project-home-builder' | 'bilko-host-publisher';
+
 /** One global `~/.claude/agents/<name>.md` persona, per the Agent Library nav page. */
 export interface AgentPersona {
   name: string;
@@ -207,7 +212,7 @@ export interface AgentPersona {
   model: string | null;
   color: string | null;
   /** Epic intent tags (tagLibrary.ts's TAG_LIBRARY) this persona is associated with. */
-  tags: string[];
+  tags: AgentPersonaTag[];
   /** Project cwds whose Sessions toolbar shows a one-click Action button for this
    *  agent. The single entry `'*'` means every project. Empty = no Action button. */
   projects: string[];
@@ -234,7 +239,7 @@ export interface AgentPersonaSaveInput {
   tools: string[];
   model: string;
   color: string;
-  tags: string[];
+  tags: AgentPersonaTag[];
   /** Project cwds (or the `'*'` sentinel) this persona's Action button appears in. */
   projects?: string[];
   /** Opening instruction sent by this persona's Action button. */

package/dist/assets/AgentLibrary-D0frFrHG.js

@@ -1,3 +0,0 @@
-import{_ as e,t as U,a5 as m,g as B,b as D,ae as b,ab as V,T as X,ad as Z,al as ee,A as R}from"./index-DJ6xdB0r.js";import{P as te}from"./Panel-DigZB9Yd.js";import{L as ne}from"./ListDetail-DXd5rB2F.js";import"./monaco-editor-BW5C4Iv1.js";function y({children:t,onClick:o,disabled:x,variant:g="default",tooltip:i,type:f="button",className:u}){const v=`px-2 py-0.5 text-xs rounded border transition-colors disabled:opacity-40 disabled:cursor-not-allowed ${g==="primary"?"text-accent border-accent/50 hover:bg-bg-hi":g==="danger"?"text-red-400 hover:text-red-300 border-line hover:border-red-400/50":"text-fg-dim border-line hover:text-fg hover:bg-bg-hi"} ${u??""}`,a=e.jsx("button",{type:f,title:i,onClick:o,disabled:x,className:v,children:t});return i?e.jsx(U,{content:i,align:"bottom-center",children:a}):a}const ae=["inherit","haiku","sonnet","opus"],I=["Read","Grep","Glob","Bash","Write","Edit","WebFetch","WebSearch","Task"],se=["","red","orange","yellow","green","cyan","blue","purple","pink"],z={red:"#c0392b",orange:"#b85c34",yellow:"#c9a227",green:"#6f7d52",cyan:"#3f8f8a",blue:"#4a6fa5",purple:"#7a6a8a",pink:"#b45a80"};function T(t){return{name:t.name,description:t.description??"",tools:t.tools,model:t.model??"inherit",color:t.color??"",tags:t.tags,projects:t.projects??[],action:t.action??"",actionLabel:t.actionLabel??"",body:t.body}}const _={name:"new-agent",description:"",tools:["Read","Grep"],model:"inherit",color:"",tags:[],projects:[],action:"",actionLabel:"",body:""};function re(){const[t,o]=m.useState(null),[x,g]=m.useState(null),[i,f]=m.useState(""),[u,c]=m.useState(null),[v,a]=m.useState(!1),[j,N]=m.useState(!1),[O,C]=m.useState(null),[k,s]=m.useState(!1),w=m.useRef(!0);m.useEffect(()=>()=>{w.current=!1},[]);const h=async n=>{try{const d=await window.api.agents.listPersonas();if(!w.current)return;o(d),g(L=>{var P;return n??L??((P=d[0])==null?void 0:P.name)??null})}catch(d){if(!w.current)return;o([]),b.error(d.message||"failed to load agent personas")}};if(m.useEffect(()=>{h()},[]),m.useEffect(()=>window.api.agents.onChanged(()=>h()),[]),m.useEffect(()=>{const n=V();n&&g(n);const d=L=>g(L.detail);return window.addEventListener("sm:select-persona",d),()=>window.removeEventListener("sm:select-persona",d)},[]),t===null)return e.jsx(B,{title:"loading…"});const $=i.toLowerCase(),E=t.filter(n=>!$||n.name.toLowerCase().includes($)||(n.description??"").toLowerCase().includes($)),l=t.find(n=>n.name===x)??t[0]??null,r=u??(l?T(l):null),F=!!u&&!!l&&JSON.stringify(u)!==JSON.stringify(T(l)),S=v,G=n=>{c(null),a(!1),N(!1),C(null),g(n)},M=n=>c(d=>({...d??(l?T(l):_),...n})),W=()=>{c({..._}),a(!0),N(!1)},J=()=>{r&&(c({...r,name:r.name+"-copy"}),a(!0))},K=()=>{c(null),a(!1)},H=async()=>{if(r){if(!/^[a-z][a-z0-9-]*$/.test(r.name)){b.error('agent name must be lowercase, hyphenated (e.g. "my-agent")');return}s(!0);try{const n={name:r.name,originalName:S||l==null?void 0:l.name,description:r.description,tools:r.tools,model:r.model,color:r.color,tags:r.tags,projects:r.projects,action:r.action,actionLabel:r.actionLabel,body:r.body};await window.api.agents.savePersona(n),b.info(S?`created ${r.name}`:`saved ${r.name}`),c(null),a(!1),await h(r.name)}catch(n){b.error(n.message||"failed to save agent persona")}finally{s(!1)}}},Y=async()=>{if(l){s(!0);try{await window.api.agents.deletePersona({name:l.name}),b.info(`deleted ${l.name}`),N(!1),c(null),a(!1),await h()}catch(n){b.error(n.message||"failed to delete agent persona")}finally{s(!1)}}},q=async n=>{s(!0);try{await window.api.agents.deletePersona({name:n}),b.info(`deleted ${n}`),C(null),x===n&&(c(null),a(!1)),await h()}catch(d){b.error(d.message||"failed to delete agent persona")}finally{s(!1)}},Q=async n=>{if(l)try{await window.api.agents.removeOverride({name:l.name,projectName:n}),b.info(`removed ${n}'s override of ${l.name}`),await h(l.name)}catch(d){b.error(d.message||"failed to remove override")}};return e.jsx(te,{toolbar:e.jsxs(e.Fragment,{children:[e.jsxs("span",{className:"text-fg-faint",children:[t.length," persona",t.length===1?"":"s"]}),e.jsx("input",{value:i,onChange:n=>f(n.target.value),placeholder:"filter…",className:"bg-bg border border-line rounded px-2 py-0.5 text-xs text-fg w-40"}),e.jsx("div",{className:"flex-1"}),e.jsx(y,{variant:"primary",onClick:W,children:"+ New agent"})]}),children:e.jsx(ne,{sidebar:e.jsxs("div",{className:"py-1",children:[S&&e.jsx("div",{className:"w-full text-left px-3 py-1 text-xs flex flex-col gap-0.5 bg-bg-hi text-fg border-l-2 border-accent",children:e.jsxs("span",{className:"flex items-center gap-2 justify-between w-full",children:[e.jsx("span",{className:"truncate font-mono",children:r==null?void 0:r.name}),e.jsx("span",{className:"shrink-0 text-[10px] font-semibold text-accent",children:"new"})]})}),E.length===0&&!S?e.jsx("div",{className:"px-3 py-1 text-xs text-fg-faint italic",children:"no agent personas found"}):E.map(n=>{const d=!S&&n.name===x,L=d&&F,P=O===n.name;return e.jsxs("div",{"data-agent-row":n.name,className:`group w-full text-left px-3 py-1 text-xs flex flex-col gap-0.5 border-l-2 cursor-pointer ${d?"bg-bg-hi text-fg border-accent":"text-fg-dim hover:text-fg hover:bg-bg-hi border-transparent"}`,onClick:()=>G(n.name),children:[e.jsxs("span",{className:"flex items-center gap-2 justify-between w-full",children:[e.jsxs("span",{className:"flex items-center gap-1.5 min-w-0",children:[e.jsx("span",{className:"w-2 h-2 rounded-sm shrink-0",style:{background:n.color?z[n.color]??n.color:"var(--fg-faint, #999)",opacity:n.color?1:.35}}),e.jsx("span",{className:"truncate font-mono",children:n.name})]}),e.jsxs("span",{className:"shrink-0 flex items-center gap-1.5",children:[L&&e.jsx("span",{className:"text-[10px] font-semibold text-accent",children:"unsaved"}),!L&&n.overridingProjects.length>0&&e.jsxs(D,{tone:"dim",children:[n.overridingProjects.length," override",n.overridingProjects.length>1?"s":""]}),P?e.jsxs("span",{className:"flex items-center gap-1",onClick:A=>A.stopPropagation(),children:[e.jsx("button",{onClick:()=>q(n.name),disabled:k,title:`Delete ${n.name}`,className:"text-[10px] font-semibold text-red-400 hover:text-red-300",children:"confirm"}),e.jsx("button",{onClick:()=>C(null),title:"Cancel",className:"text-[10px] text-fg-faint hover:text-fg",children:"cancel"})]}):e.jsx("button",{onClick:A=>{A.stopPropagation(),C(n.name)},title:`Delete ${n.name}`,className:"opacity-0 group-hover:opacity-100 text-fg-faint hover:text-red-400 transition-opacity",children:"×"})]})]}),n.description&&e.jsx("span",{className:"truncate text-fg-faint",children:n.description})]},n.name)})]}),detail:r?e.jsx(oe,{obj:r,set:M,saved:l,dirty:F,isNew:S,busy:k,confirmDelete:j,setConfirmDelete:N,onDuplicate:J,onRevert:K,onSave:H,onDelete:Y,onDropOverride:Q}):e.jsx(B,{title:"select an agent"})})})}const fe=m.memo(re);function oe({obj:t,set:o,saved:x,dirty:g,isNew:i,busy:f,confirmDelete:u,setConfirmDelete:c,onDuplicate:v,onRevert:a,onSave:j,onDelete:N,onDropOverride:O}){const C=`~/.claude/agents/${t.name}.md`,k=g||i;return e.jsxs("div",{className:"max-w-3xl",children:[e.jsxs("div",{className:"px-4 py-3 border-b border-line flex items-center gap-2 flex-wrap",children:[e.jsx("span",{className:"text-sm font-semibold text-fg font-mono",children:t.name}),i?e.jsx(D,{tone:"accent",children:"unsaved draft"}):g?e.jsx(D,{tone:"warn",children:"edited"}):e.jsx(D,{tone:"good",children:"saved"}),e.jsx("span",{className:"ml-auto text-[11px] text-fg-faint font-mono",children:C})]}),e.jsxs("div",{className:"p-4 space-y-4",children:[e.jsx(p,{label:"name",hint:"Filename on disk — lowercase, hyphenated.",children:e.jsx("input",{value:t.name,onChange:s=>o({name:s.target.value.toLowerCase()}),className:"w-full bg-bg border border-line rounded px-2 py-1 text-xs text-fg font-mono"})}),e.jsx(p,{label:"description",hint:"Shown in the list and in agent pickers.",children:e.jsx("input",{value:t.description,onChange:s=>o({description:s.target.value}),className:"w-full bg-bg border border-line rounded px-2 py-1 text-xs text-fg"})}),e.jsx(p,{label:"default model",hint:"This persona's default model for its Epics — sets the --model an Epic launches with (Terminal + Chat both honor it). 'inherit' falls back to each view's own default, not this Settings page. Cheap models for read-only personas; opus for judgement calls.",children:e.jsx(le,{options:ae,value:t.model,onChange:s=>o({model:s}),mono:!0})}),e.jsx(p,{label:"tools",hint:`${t.tools.length} of ${I.length} granted. Anything not ticked is refused at call time.`,children:e.jsx("div",{className:"flex flex-wrap gap-1.5",children:I.map(s=>{const w=t.tools.includes(s);return e.jsx("button",{onClick:()=>o({tools:w?t.tools.filter(h=>h!==s):[...t.tools,s]}),className:`px-2 py-0.5 rounded-full text-[11px] font-mono border ${w?"bg-sage/15 text-sage-dark border-sage/30":"bg-bg-hi text-fg-faint border-line"}`,children:s},s)})})}),e.jsx(p,{label:"color",children:e.jsx("div",{className:"flex gap-1.5",children:se.map(s=>e.jsx("button",{title:s||"none",onClick:()=>o({color:s}),className:"w-5 h-5 rounded",style:{background:s?z[s]:"transparent",border:t.color===s?"2px solid var(--accent, #b85c34)":"1px solid var(--line, #555)"}},s||"none"))})}),e.jsx(p,{label:"tags",hint:"Session mission tags this persona is associated with — shown as the default agent on that tag's own page. The first one (in Tag Library order) is the MISSION an Action button's session opens with.",children:e.jsx("div",{className:"flex flex-wrap gap-1.5",children:X.map(s=>{const w=t.tags.includes(s.tag),h=Z(s.tag);return e.jsxs("button",{onClick:()=>o({tags:w?t.tags.filter($=>$!==s.tag):[...t.tags,s.tag]}),className:`px-2 py-0.5 rounded-full text-[11px] font-mono border ${w?`${h.bg} ${h.text} ${h.border?"border-current/30":"border-transparent"}`:"bg-bg-hi text-fg-faint border-line"}`,children:["#",s.tag]},s.tag)})})}),e.jsx(ie,{obj:t,set:o}),e.jsx(p,{label:"definition",hint:"The system prompt this persona runs under.",children:e.jsx("textarea",{rows:9,value:t.body,onChange:s=>o({body:s.target.value}),className:"w-full bg-bg border border-line rounded px-2 py-1.5 text-xs text-fg font-mono leading-relaxed resize-y"})}),e.jsx(p,{label:"project overrides",hint:"Open projects that shadow this definition with a local copy.",children:x&&x.overridingProjects.length>0?e.jsx("div",{className:"flex flex-wrap gap-1.5",children:x.overridingProjects.map(s=>e.jsxs("span",{className:"inline-flex items-center gap-1.5 bg-bg-elev border border-line rounded px-2 py-0.5 text-[11px] font-mono text-fg-dim",children:[s,e.jsx("button",{onClick:()=>O(s),title:"Drop the local copy",className:"text-fg-faint hover:text-fg",children:"×"})]},s))}):e.jsx("div",{className:"text-xs text-fg-faint italic",children:i?"save first to see project overrides.":"no open project overlays this agent — the global definition applies everywhere."})})]}),e.jsx("div",{className:"px-4 py-2.5 border-t border-line flex items-center gap-2 flex-wrap",children:u?e.jsxs(e.Fragment,{children:[e.jsxs("span",{className:"text-xs text-fg-dim",children:["Delete ",e.jsx("strong",{className:"font-mono",children:t.name})," and its file?"]}),e.jsx(y,{variant:"danger",onClick:N,disabled:f,children:"Delete"}),e.jsx(y,{onClick:()=>c(!1),children:"Keep"})]}):e.jsxs(e.Fragment,{children:[e.jsx(y,{onClick:v,disabled:f,children:"Duplicate"}),!i&&e.jsx(y,{variant:"danger",onClick:()=>c(!0),disabled:f,children:"Delete"}),e.jsx("div",{className:"flex-1"}),k&&e.jsx("span",{className:"text-[11px] text-fg-faint",children:"unsaved changes"}),e.jsx(y,{onClick:a,disabled:!k||f,children:"Revert"}),e.jsx(y,{variant:"primary",onClick:j,disabled:!k||f,children:f?"Saving…":i?"Create":"Save"})]})})]})}function ie({obj:t,set:o}){const{projects:x}=ee(),g=x.map(a=>({cwd:a.cwd,name:a.name})),i=new Set(g.map(a=>a.cwd)),f=t.projects.filter(a=>a!==R&&!i.has(a)),u=t.projects.includes(R),c=a=>o({projects:t.projects.includes(a)?t.projects.filter(j=>j!==a):[...t.projects,a]}),v=t.projects.length>0;return e.jsxs(e.Fragment,{children:[e.jsx(p,{label:"action — appears in",hint:"Projects whose Sessions toolbar gets a one-click button for this agent. Pressing it starts a normal session: this persona is the ACTOR, its first tag is the MISSION, and the action text below is the opening goal. Leave empty for an agent that is only picked by hand in the New Session card.",children:e.jsxs("div",{className:"flex flex-wrap gap-1.5",children:[e.jsx("button",{onClick:()=>c(R),className:`px-2 py-0.5 rounded-full text-[11px] font-mono border ${u?"bg-accent/15 text-accent border-accent/40 font-semibold":"bg-bg-hi text-fg-faint border-line"}`,children:"every project"}),g.map(a=>{const j=t.projects.includes(a.cwd);return e.jsx("button",{title:a.cwd,onClick:()=>c(a.cwd),className:`px-2 py-0.5 rounded-full text-[11px] font-mono border ${j?"bg-sage/15 text-sage-dark border-sage/30":"bg-bg-hi text-fg-faint border-line"} ${u&&!j?"opacity-40":""}`,children:a.name},a.cwd)}),f.map(a=>e.jsxs("button",{title:`${a} — not a known project on this machine`,onClick:()=>c(a),className:"px-2 py-0.5 rounded-full text-[11px] font-mono border bg-bg-hi text-fg-faint border-dashed border-line",children:[a," ×"]},a))]})}),v&&e.jsxs(e.Fragment,{children:[e.jsx(p,{label:"action — button label",hint:"Caption on the Sessions toolbar button. Defaults to the agent name.",children:e.jsx("input",{value:t.actionLabel,onChange:a=>o({actionLabel:a.target.value}),placeholder:t.name,className:"w-full bg-bg border border-line rounded px-2 py-1 text-xs text-fg"})}),e.jsx(p,{label:"action — opening instruction",hint:"Sent as the session's first message, under the AIM framing. Falls back to this persona's description when empty; with neither, no button is shown.",children:e.jsx("textarea",{rows:3,value:t.action,onChange:a=>o({action:a.target.value}),placeholder:t.description||`e.g. /builder
-
-Check git vs the published package and publish anything new.`,className:"w-full bg-bg border border-line rounded px-2 py-1.5 text-xs text-fg font-mono leading-relaxed resize-y"})})]})]})}function p({label:t,hint:o,children:x}){return e.jsxs("div",{children:[e.jsx("div",{className:"text-[10.5px] font-semibold uppercase tracking-wide text-fg-faint mb-1.5 font-mono",children:t}),x,o&&e.jsx("div",{className:"text-[11px] text-fg-faint mt-1 leading-snug",children:o})]})}function le({options:t,value:o,onChange:x,mono:g}){return e.jsx("div",{className:"flex flex-wrap gap-1",children:t.map(i=>{const f=i===o;return e.jsx("button",{onClick:()=>x(i),className:`px-2.5 py-1 rounded text-xs border ${g?"font-mono":""} ${f?"bg-accent/15 text-accent border-accent/40 font-semibold":"bg-bg-hi text-fg-dim border-line"}`,children:i},i)})})}export{fe as AgentLibrary};