claude-code-session-manager 0.73.2 → 0.75.0

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/delegationReadiness.cjs

@@ -0,0 +1,141 @@
+/**
+ * Delegation-readiness probe — answers "can this project actually hand work
+ * to the scheduler?" as structured data instead of a silent tool-list gap.
+ *
+ * Why this exists: when the session-manager-scheduler MCP server isn't
+ * registered, `scheduler_create_prd` is simply absent from the agent's tool
+ * list — there's no error to catch, so an agent asked to delegate just
+ * implements inline instead. See scripts/install-scheduler-mcp-user-scope.sh's
+ * header for the incident this repeat-guards against (PRD 1024-1030).
+ *
+ * This module only computes the four checks below; surfacing them in the UI
+ * or the Epic's grounding line is a dependent PRD (delegation-readiness-ui).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const SCHEDULER_MCP_NAME = 'session-manager-scheduler';
+const DEV_PLUGIN_ENABLED_KEY = 'session-manager-dev@session-manager';
+const SCHEDULER_MCP_SERVER_SCRIPT = path.resolve(__dirname, '..', '..', '..', 'scripts', 'scheduler-mcp-server.cjs');
+
+/** Read + JSON.parse a file, returning `fallback` on any read/parse failure. */
+function readJsonSafe(absPath, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(absPath, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function checkSchedulerMcp({ cwd, homeDir }) {
+  const userConfig = readJsonSafe(path.join(homeDir, '.claude.json'), null);
+  const userHas = !!userConfig?.mcpServers?.[SCHEDULER_MCP_NAME];
+
+  const projectConfig = readJsonSafe(path.join(cwd, '.mcp.json'), null);
+  const projectHas = !!projectConfig?.mcpServers?.[SCHEDULER_MCP_NAME];
+
+  const ok = userHas || projectHas;
+  let detail;
+  if (userHas) detail = `${SCHEDULER_MCP_NAME} registered at user scope (~/.claude.json)`;
+  else if (projectHas) detail = `${SCHEDULER_MCP_NAME} registered at project scope (${cwd}/.mcp.json)`;
+  else detail = `no ${SCHEDULER_MCP_NAME} entry in ~/.claude.json or ${cwd}/.mcp.json`;
+
+  return {
+    id: 'scheduler-mcp',
+    label: 'Scheduler MCP server registered',
+    ok,
+    detail,
+    fix: ok
+      ? null
+      : `claude mcp add ${SCHEDULER_MCP_NAME} --scope user -- node ${SCHEDULER_MCP_SERVER_SCRIPT}`,
+  };
+}
+
+function checkDevPlugin({ homeDir }) {
+  const settings = readJsonSafe(path.join(homeDir, '.claude', 'settings.json'), null);
+  const ok = settings?.enabledPlugins?.[DEV_PLUGIN_ENABLED_KEY] === true;
+
+  return {
+    id: 'dev-plugin',
+    label: 'session-manager-dev plugin enabled',
+    ok,
+    detail: ok
+      ? `${DEV_PLUGIN_ENABLED_KEY} enabled in ~/.claude/settings.json`
+      : `${DEV_PLUGIN_ENABLED_KEY} missing from ~/.claude/settings.json enabledPlugins`,
+    fix: ok ? null : 'Enable in Plugins tab: session-manager-dev (Session Manager)',
+  };
+}
+
+// Personas resolve from BOTH scopes (agentLibrary.cjs: "project cwd wins
+// over the global" one) — a project that only ever defines project-scoped
+// overrides in `<cwd>/.claude/agents/` (this repo's own `.claude/agents/`
+// is exactly that case) is a legitimately delegation-ready project, not a
+// failing one, so both directories must be counted.
+function countMdFiles(dir) {
+  try {
+    return fs.readdirSync(dir).filter((f) => f.endsWith('.md')).length;
+  } catch {
+    return 0;
+  }
+}
+
+function checkAgentPersonas({ cwd, homeDir }) {
+  const globalCount = countMdFiles(path.join(homeDir, '.claude', 'agents'));
+  const projectCount = countMdFiles(path.join(cwd, '.claude', 'agents'));
+  const count = globalCount + projectCount;
+  const ok = count > 0;
+
+  return {
+    id: 'agent-personas',
+    label: 'At least one agent persona defined',
+    ok,
+    detail: ok
+      ? `${count} persona(s) across ~/.claude/agents/ and ${cwd}/.claude/agents/`
+      : `no .md personas in ~/.claude/agents/ or ${cwd}/.claude/agents/`,
+    fix: ok ? null : 'Create a persona in the Agent Library tab',
+  };
+}
+
+function checkPrdWriteGuard({ cwd }) {
+  const settings = readJsonSafe(path.join(cwd, '.claude', 'settings.json'), null);
+  const preToolUse = Array.isArray(settings?.hooks?.PreToolUse) ? settings.hooks.PreToolUse : [];
+  const ok = preToolUse.some((matcher) =>
+    Array.isArray(matcher?.hooks) &&
+    matcher.hooks.some((h) => typeof h?.command === 'string' && h.command.includes('guard-prd-writes'))
+  );
+
+  return {
+    id: 'prd-write-guard',
+    label: 'PRD-write guard hook installed',
+    ok,
+    detail: ok
+      ? `guard-prd-writes PreToolUse hook found in ${cwd}/.claude/settings.json`
+      : `no guard-prd-writes PreToolUse hook in ${cwd}/.claude/settings.json`,
+    fix: ok
+      ? null
+      : `Add a PreToolUse hook to ${cwd}/.claude/settings.json matching Write|Edit|NotebookEdit that runs node scripts/hooks/guard-prd-writes.cjs`,
+  };
+}
+
+/**
+ * Runs all four delegation-readiness checks for `cwd`. Every filesystem read
+ * is wrapped (readJsonSafe / try-catch) so a missing or unparseable file
+ * yields ok:false with a detail, never a thrown exception.
+ */
+function checkDelegationReadiness({ cwd, homeDir = os.homedir() }) {
+  const checks = [
+    checkSchedulerMcp({ cwd, homeDir }),
+    checkDevPlugin({ homeDir }),
+    checkAgentPersonas({ cwd, homeDir }),
+    checkPrdWriteGuard({ cwd }),
+  ];
+
+  return {
+    ok: checks.every((c) => c.ok),
+    checks,
+  };
+}
+
+module.exports = { checkDelegationReadiness };

package/src/main/lib/epicDelegationStats.cjs

@@ -0,0 +1,124 @@
+'use strict';
+
+/**
+ * Derived-at-read-time counters answering "did this Epic delegate work into
+ * PRDs, or did the interactive session just edit application source
+ * inline?" — no new writer, no new namespace; both numbers are computed
+ * from state that already exists on disk (single-writer law,
+ * opsOwnership.cjs).
+ *
+ * prdsQueued reads the Epic's own live PRD dir
+ * (session-manager-operations/scheduler/epics/<epicId>/prds/) — the
+ * "prds-archived" sibling deliberately does NOT count here: this is a
+ * live-delegation signal, not a lifetime PRD count (that's epicPrds() in
+ * the renderer, sourced from the scheduler's own snapshot).
+ *
+ * inlineEdits reads the Epic's OWN interactive claude session transcript —
+ * ~/.claude/projects/<encodeCwd(cwd)>/<claudeSessionId>.jsonl, the same file
+ * transcripts.cjs already tails for the live feed — and counts Write/Edit/
+ * NotebookEdit tool_use blocks whose file_path resolves under this repo's
+ * src/, scripts/, plugins/, or bin/. That transcript already carries real
+ * tool_use blocks (classifyTranscriptLine.cjs); the durable
+ * session-manager-operations/prompt-sessions/transcripts/<epicId>.jsonl
+ * store does NOT (it holds only rendered {role, text} turns, verified by
+ * reading one), so it is not a usable source for this counter.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { encodeCwd } = require('./encodeCwd.cjs');
+const { classifyLine } = require('./classifyTranscriptLine.cjs');
+
+// Same cap transcripts.cjs's readDelta uses for a single pass — bounds
+// memory/time on a very large transcript instead of reading it whole.
+const MAX_TRANSCRIPT_BYTES = 8 * 1024 * 1024;
+
+const INLINE_EDIT_TOOL_NAMES = new Set(['Write', 'Edit', 'NotebookEdit']);
+const APPLICATION_SOURCE_PREFIXES = ['src/', 'scripts/', 'plugins/', 'bin/'];
+
+function countPrdsQueued(cwd, epicId, deps = {}) {
+  const readdirSync = deps.readdirSync || fs.readdirSync;
+  try {
+    const dir = path.join(cwd, 'session-manager-operations', 'scheduler', 'epics', epicId, 'prds');
+    return readdirSync(dir).filter((name) => name.endsWith('.md')).length;
+  } catch {
+    return 0;
+  }
+}
+
+/** True when `filePath` (absolute or relative) resolves to a path under
+ *  cwd's src/, scripts/, plugins/, or bin/ — never a dotfile/root config,
+ *  never a path outside the repo entirely. */
+function isApplicationSourcePath(cwd, filePath) {
+  if (typeof filePath !== 'string' || !filePath) return false;
+  const rel = path.relative(cwd, path.resolve(cwd, filePath)).split(path.sep).join('/');
+  if (rel.startsWith('..')) return false;
+  return APPLICATION_SOURCE_PREFIXES.some((prefix) => rel === prefix.slice(0, -1) || rel.startsWith(prefix));
+}
+
+/** Reads at most the trailing MAX_TRANSCRIPT_BYTES of `filePath`, dropping
+ *  a truncated leading partial line when the read didn't start at byte 0. */
+function readTranscriptTail(filePath, deps = {}) {
+  const statSync = deps.statSync || fs.statSync;
+  const openSync = deps.openSync || fs.openSync;
+  const readSync = deps.readSync || fs.readSync;
+  const closeSync = deps.closeSync || fs.closeSync;
+
+  const size = statSync(filePath).size;
+  const start = Math.max(0, size - MAX_TRANSCRIPT_BYTES);
+  const length = size - start;
+  const buffer = Buffer.alloc(length);
+  const fd = openSync(filePath, 'r');
+  try {
+    readSync(fd, buffer, 0, length, start);
+  } finally {
+    closeSync(fd);
+  }
+  const text = buffer.toString('utf8');
+  return start > 0 ? text.slice(text.indexOf('\n') + 1) : text;
+}
+
+function countInlineEdits(cwd, claudeSessionId, deps = {}) {
+  if (!claudeSessionId) return 0;
+  const readFn = deps.readTranscriptTail || readTranscriptTail;
+  const homeDir = deps.homeDir || os.homedir();
+  try {
+    const filePath = path.join(homeDir, '.claude', 'projects', encodeCwd(cwd), `${claudeSessionId}.jsonl`);
+    const text = readFn(filePath, deps);
+    let count = 0;
+    for (const line of text.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      let obj;
+      try {
+        obj = JSON.parse(trimmed);
+      } catch {
+        continue;
+      }
+      for (const event of classifyLine(obj)) {
+        if (event.kind !== 'tool_use') continue;
+        const { name, input } = event.data || {};
+        if (!INLINE_EDIT_TOOL_NAMES.has(name)) continue;
+        if (isApplicationSourcePath(cwd, input?.file_path)) count += 1;
+      }
+    }
+    return count;
+  } catch {
+    return 0;
+  }
+}
+
+function computeEpicDelegationStats(cwd, epicId, claudeSessionId, deps = {}) {
+  return {
+    prdsQueued: countPrdsQueued(cwd, epicId, deps),
+    inlineEdits: countInlineEdits(cwd, claudeSessionId, deps),
+  };
+}
+
+module.exports = {
+  computeEpicDelegationStats,
+  countPrdsQueued,
+  countInlineEdits,
+  isApplicationSourcePath,
+};

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({
@@ -49,7 +41,7 @@ const EpicSourceSchema = z.object({
 // data so the Epic's first turn can render a structured AIM briefing card
 // instead of regex-parsing the flat string back apart.
 const EpicIntakeSectionSchema = z.object({
-  kind: z.enum(['actor', 'injection', 'input', 'mission', 'goal', 'reference']),
+  kind: z.enum(['actor', 'persona-body', 'injection', 'input', 'mission', 'goal', 'reference']),
   label: z.string(),
   text: z.string(),
   source: z.string().optional(),

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/main/seedAgentPersonas.cjs

@@ -0,0 +1,92 @@
+/**
+ * First-boot seeder for the bundled Agent personas (Architect, Dev Lead).
+ *
+ * On a fresh install `~/.claude/agents/` is empty, so the Agent Library has
+ * nothing to offer — no persona to select for an Epic's Actor. This seeder
+ * copies the personas bundled at `src/seed/agents/*.md` into `~/.claude/agents/`
+ * on first boot, one file per persona, and NEVER overwrites a file that
+ * already exists there (hand-edited or user-authored personas win).
+ *
+ * Idempotent the same way as seedDevPlugin.cjs:
+ *   1. A marker file (`~/.claude/session-manager/.agent-personas-seeded`)
+ *      records seed state. Once seeding SUCCEEDS we write `done` and never
+ *      touch it again. A FAILED attempt only bumps an attempt counter and
+ *      retries on the next few boots (bounded by MAX_ATTEMPTS), so a
+ *      transient first-boot failure doesn't permanently skip the personas.
+ *
+ * Fire-and-forget: called post-window from index.cjs. Errors are logged,
+ * never thrown. Kill-switch: SM_SEED_AGENT_PERSONAS_DISABLE=1.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { writeJsonSync } = require('./config.cjs');
+
+const PERSONAS = ['architect', 'dev-lead'];
+const MAX_ATTEMPTS = 3; // give a transient first-boot failure a few chances
+
+function bundledSourceDir() {
+  return path.join(__dirname, '..', 'seed', 'agents');
+}
+
+function destAgentsDir() {
+  return path.join(os.homedir(), '.claude', 'agents');
+}
+
+function markerPath() {
+  return path.join(os.homedir(), '.claude', 'session-manager', '.agent-personas-seeded');
+}
+
+/** Read the marker → { done:boolean, attempts:number }. Absent = fresh. */
+function readMarker() {
+  try {
+    const raw = fs.readFileSync(markerPath(), 'utf8').trim();
+    const m = JSON.parse(raw);
+    return { done: !!m.done, attempts: Number(m.attempts) || 0 };
+  } catch {
+    return { done: false, attempts: 0 };
+  }
+}
+
+function writeMarker(state) {
+  try {
+    writeJsonSync(markerPath(), { ...state, ts: new Date().toISOString() });
+  } catch (err) {
+    console.warn('[seedAgentPersonas] could not write marker:', err?.message ?? err);
+  }
+}
+
+async function seedAgentPersonas({ logger = console, writeLog = () => {} } = {}) {
+  if (process.env.SM_SEED_AGENT_PERSONAS_DISABLE === '1') return;
+  const marker = readMarker();
+  if (marker.done) return;                       // succeeded before — leave it alone.
+  if (marker.attempts >= MAX_ATTEMPTS) return;   // gave up — manual copy only.
+
+  try {
+    const srcDir = bundledSourceDir();
+    const destDir = destAgentsDir();
+    fs.mkdirSync(destDir, { recursive: true });
+
+    for (const name of PERSONAS) {
+      const src = path.join(srcDir, `${name}.md`);
+      const dest = path.join(destDir, `${name}.md`);
+      if (fs.existsSync(dest)) continue; // never overwrite an existing persona
+      fs.copyFileSync(src, dest);
+      logger.log?.(`[seedAgentPersonas] seeded ${name}.md`);
+    }
+
+    writeMarker({ done: true, attempts: marker.attempts });
+  } catch (err) {
+    logger.warn?.('[seedAgentPersonas] error:', err?.message ?? err);
+    writeLog({
+      scope: 'seed-agent-personas',
+      level: 'error',
+      message: 'seed error',
+      meta: { error: err?.message ?? String(err), attempt: marker.attempts + 1, maxAttempts: MAX_ATTEMPTS },
+    });
+    writeMarker({ done: false, attempts: marker.attempts + 1 });
+  }
+}
+
+module.exports = { seedAgentPersonas, markerPath, MAX_ATTEMPTS };