claude-code-session-manager 0.122.1 → 0.123.1

package/src/main/lib/epic/epicStandingInstructions.cjs

@@ -0,0 +1,73 @@
+'use strict';
+/**
+ * epicStandingInstructions.cjs — turns an Epic record into the text Session
+ * Manager passes as --append-system-prompt on EVERY turn of that Epic, so the
+ * Actor's operating rules survive later turns and compaction.
+ *
+ * buildEpicStandingInstructions is pure; the persona reader is injected.
+ */
+
+const HEADER = 'Standing instructions for this Epic (re-sent every turn by Session Manager):';
+const MAX_CHARS = 12000;
+const TRUNCATION_NOTICE = '\n\n[…standing instructions truncated at 12000 characters]';
+const INCLUDED_KINDS = new Set(['actor', 'persona-body', 'injection', 'mission']);
+
+// Must equal CONTEXT_INJECTIONS['delegate-implementation'].text in
+// src/renderer/lib/contextInjections.ts (guarded by delegateTextDrift.test.ts).
+const DELEGATE_IMPLEMENTATION_TEXT =
+  'This interactive session plans and decides; it does not implement. Once scope is clear, ' +
+  'queue the implementation as scheduled PRDs via the /develop skill and let it run headless — ' +
+  'do not edit application source inline in this conversation. If the scheduler tools are ' +
+  'unavailable, say so explicitly rather than falling back to implementing the work yourself.';
+
+function cap(text) {
+  if (text.length <= MAX_CHARS) return text;
+  return text.slice(0, MAX_CHARS - TRUNCATION_NOTICE.length) + TRUNCATION_NOTICE;
+}
+
+function buildEpicStandingInstructions(epic, { readPersonaBody } = {}) {
+  if (!epic || typeof epic !== 'object') return null;
+  const sections = Array.isArray(epic.sections) ? epic.sections : [];
+  const parts = [];
+  if (sections.length > 0) {
+    for (const s of sections) {
+      if (!s || !INCLUDED_KINDS.has(s.kind)) continue;
+      const t = typeof s.text === 'string' ? s.text.trim() : '';
+      if (t) parts.push(t);
+    }
+  } else if (epic.agentType && typeof readPersonaBody === 'function') {
+    let body = null;
+    try { body = readPersonaBody(epic.agentType); } catch { body = null; }
+    const t = typeof body === 'string' ? body.trim() : '';
+    if (t) parts.push(t);
+  }
+
+  const wantsDelegate = epic.tag === 'feature' || epic.tag === 'bug' || epic.agentType === 'architect';
+  const hasDelegate = sections.some(
+    (s) => s && s.kind === 'injection' && s.source === 'delegate-implementation',
+  );
+  if (wantsDelegate && !hasDelegate) parts.push(DELEGATE_IMPLEMENTATION_TEXT);
+
+  if (parts.length === 0) return null;
+  return cap(`${HEADER}\n\n${parts.join('\n\n')}`);
+}
+
+/** Overlay-aware persona body (project .claude/agents wins over ~/.claude/agents), frontmatter stripped. */
+function defaultReadPersonaBody(cwd, name) {
+  try {
+    const { resolveMergedPersona } = require('../persona-macro/personaMerge.cjs');
+    const merged = resolveMergedPersona(cwd, name);
+    const body = merged && typeof merged.body === 'string' ? merged.body.trim() : '';
+    return body || null;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  buildEpicStandingInstructions,
+  defaultReadPersonaBody,
+  DELEGATE_IMPLEMENTATION_TEXT,
+  HEADER,
+  MAX_CHARS,
+};

package/src/main/lib/epic/guardSpawnSettings.cjs

@@ -0,0 +1,76 @@
+/**
+ * guardSpawnSettings.cjs — builds the Claude Code settings object carrying
+ * Session Manager's four PreToolUse guard hooks for ONE claude spawn, and
+ * writes it to a stable file for `claude --settings <file>`.
+ *
+ * Why: Epic chats and scheduler jobs run in git worktrees that carry only
+ * tracked files, so guards written into an untracked project
+ * .claude/settings.json never load there; `--settings` does.
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const crypto = require('node:crypto');
+const { GUARD_DEFS, checkGuard } = require('./delegationReadiness.cjs');
+const { shimPath: guardShimPath, ensureGuardShimsOrError } = require('../guardShims.cjs');
+const { nodeShellCommand } = require('../appRuntime.cjs');
+const { writeTextAtomic } = require('../util/atomicFs.cjs');
+
+/**
+ * @param {{ spawnCwd: string, homeDir?: string }} opts
+ * @returns {{ hooks: { PreToolUse: Array<{ matcher: string, hooks: Array<{ type: string, command: string }> }> } } | null}
+ */
+function buildGuardSpawnSettings({ spawnCwd, homeDir = os.homedir() }) {
+  const byMatcher = new Map();
+  for (const def of Object.values(GUARD_DEFS)) {
+    if (checkGuard(def, { cwd: spawnCwd, homeDir }).ok) continue;
+    if (!byMatcher.has(def.matcher)) byMatcher.set(def.matcher, []);
+    byMatcher.get(def.matcher).push({
+      type: 'command',
+      command: nodeShellCommand(guardShimPath(def.scriptBasename, homeDir)),
+    });
+  }
+  if (byMatcher.size === 0) return null;
+  return {
+    hooks: {
+      PreToolUse: [...byMatcher].map(([matcher, hooks]) => ({ matcher, hooks })),
+    },
+  };
+}
+
+/**
+ * Write the settings to <homeDir>/.claude/session-manager/spawn-settings/
+ * guards-<sha1[0..12]>.json (content-addressed) and return its absolute path.
+ * Returns null (logged, never thrown) when nothing needs injecting or the
+ * shims cannot be ensured.
+ *
+ * @param {{ spawnCwd: string, homeDir?: string, deps?: { ensureShims?: (homeDir: string) => Promise<any> } }} opts
+ * @returns {Promise<string | null>}
+ */
+async function writeGuardSpawnSettingsFile({ spawnCwd, homeDir = os.homedir(), deps = {} }) {
+  const ensureShims = deps.ensureShims || ensureGuardShimsOrError;
+  try {
+    const settings = buildGuardSpawnSettings({ spawnCwd, homeDir });
+    if (!settings) return null;
+    const shimError = await ensureShims(homeDir);
+    if (shimError) {
+      console.warn(`[guardSpawnSettings] guard shims unavailable: ${shimError.error ?? shimError}`);
+      return null;
+    }
+    const content = `${JSON.stringify(settings, null, 2)}\n`;
+    const hash = crypto.createHash('sha1').update(content).digest('hex').slice(0, 12);
+    const dir = path.join(homeDir, '.claude', 'session-manager', 'spawn-settings');
+    const file = path.join(dir, `guards-${hash}.json`);
+    if (fs.existsSync(file)) return file;
+    fs.mkdirSync(dir, { recursive: true });
+    await writeTextAtomic(file, content);
+    return file;
+  } catch (err) {
+    console.warn(`[guardSpawnSettings] could not write spawn settings: ${err?.message ?? err}`);
+    return null;
+  }
+}
+
+module.exports = { buildGuardSpawnSettings, writeGuardSpawnSettingsFile };

package/src/main/lib/feedback-remote/crossProjectFeedback.cjs

@@ -79,6 +79,7 @@ const {
 const { appendAuditEvent } = require('../telemetry/auditLog.cjs');
 const { OPS_ROOT_DIR } = require('../opsOwnership.cjs');
 const { resolveProjectContext } = require('../projectRootResolve.cjs');
+const { isEphemeralCwd } = require('../ephemeralCwd.cjs');
 
 /** Only these three Epic tags make sense for an inbound report — they are
  *  exactly the tags that route through /develop (tagLibrary.ts). 'build' and
@@ -680,8 +681,14 @@ async function listFeedbackTargets({ limit = TARGET_SCAN_LIMIT, projectsDir } =
 
   const byCwd = new Map();
   for (const { full, mtimeMs } of scanned) {
-    const cwd = await resolveCwdFromTranscriptDir(full);
-    if (!cwd) continue;
+    const rawCwd = await resolveCwdFromTranscriptDir(full);
+    if (!rawCwd) continue;
+    // Job/Epic worktrees carry a tracked operations root too, so each would
+    // list as a project. Collapse to the main checkout (same resolver the
+    // admin routes use); a worktree whose main checkout can't be proven
+    // stays ephemeral/worktree-shaped and is dropped, never listed.
+    const cwd = resolveProjectContext({ cwd: rawCwd }).cwd;
+    if (!cwd || isEphemeralCwd(cwd)) continue;
     const prior = byCwd.get(cwd);
     if (!prior || prior.lastActivity < mtimeMs) byCwd.set(cwd, { cwd, lastActivity: mtimeMs });
   }

package/src/main/lib/feedback-remote/remoteClientSessions.cjs

@@ -24,14 +24,12 @@ function clientKeyOf(envelope) {
   return LEGACY_CLIENT_KEY
 }
 
-function makeRecord(key, clientId) {
+function makeRecord(key) {
   return {
     key,
-    clientId: typeof clientId === 'string' ? clientId : null,
     e2e: makeState(),
     peerPubKey: null,
     deviceId: null,
-    ptyStreams: new Map(),
     subscriptions: new Set(),
     lastSessionListJson: null,
   }
@@ -43,10 +41,6 @@ function createClientSessions() {
   function teardown(key) {
     const rec = records.get(key)
     if (!rec) return null
-    for (const unsub of rec.ptyStreams.values()) {
-      try { if (typeof unsub === 'function') unsub() } catch { /* swallow */ }
-    }
-    rec.ptyStreams.clear()
     rec.subscriptions.clear()
     records.delete(key)
     return rec
@@ -55,13 +49,11 @@ function createClientSessions() {
   return {
     clientKeyOf,
     get: (key) => records.get(key) || null,
-    getOrCreate(key, { clientId = null } = {}) {
+    getOrCreate(key) {
       let rec = records.get(key)
       if (!rec) {
-        rec = makeRecord(key, clientId)
+        rec = makeRecord(key)
         records.set(key, rec)
-      } else if (rec.clientId === null && typeof clientId === 'string') {
-        rec.clientId = clientId
       }
       return rec
     },

package/src/main/lib/feedback-remote/remoteE2eCrypto.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
 // E2E encryption helpers (P-256 ECDH + AES-256-GCM, ADR §5.2).
-// Shared by the agent side (webRemote.cjs) and the desktop client role.
+// Used by the agent side (webRemote.cjs).
 
 const crypto = require('node:crypto');
 

package/src/main/lib/git/gitWorktree.cjs

@@ -894,15 +894,20 @@ async function createWorktree({ kind, cwd, key, fromRef }) {
     carriedPaths = carry.paths;
   }
 
+  let setup = { ran: false, ok: false, reason: 'dep-link-disabled', waitedMs: 0, ms: 0, commands: [] };
   if (process.env.SM_WORKTREE_DEP_LINK_DISABLE !== '1') {
     try {
-      const { linked } = await require('./worktreeDeps.cjs').linkDependencyDirs({ mainCwd: cwd, worktreeCwd: dir });
-      if (linked.length) console.log(`[gitWorktree] linked deps: ${linked.join(', ')} -> ${dir}`);
-    } catch { /* best-effort — never fails worktree creation */ }
+      const deps = await require('./worktreeDeps.cjs').linkDependencyDirs({ mainCwd: cwd, worktreeCwd: dir });
+      setup = deps.setup;
+      if (deps.linked.length) console.log(`[gitWorktree] linked deps: ${deps.linked.join(', ')} -> ${dir}`);
+    } catch (err) {
+      // best-effort — never fails worktree creation
+      setup = { ran: false, ok: false, reason: 'error', error: String((err && err.message) || err), waitedMs: 0, ms: 0, commands: [] };
+    }
   }
 
   registeredCheckouts.set(dir, { kind, branch });
-  const result = { ok: true, dir, branch, baseCwd: cwd, carriedPaths, baseBranch };
+  const result = { ok: true, dir, branch, baseCwd: cwd, carriedPaths, baseBranch, setup };
   if (resolvedFromRefSha) result.forkedFrom = fromRef;
   return result;
 }

package/src/main/lib/git/worktreeDeps.cjs

@@ -44,6 +44,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { execFile } = require('node:child_process');
 const { execGit } = require('./gitExec.cjs');
+const { runWorktreeSetup } = require('./worktreeSetup.cjs');
 
 const DEFAULT_DEP_DIRS = ['node_modules', '.venv', 'venv'];
 
@@ -191,7 +192,7 @@ function addExcludes(mainCwd, names) {
 
 /**
  * @param {{ mainCwd: string, worktreeCwd: string, names?: string[] }} opts
- * @returns {Promise<{ linked: string[], skipped: string[], installed: string[] }>}
+ * @returns {Promise<{ linked: string[], skipped: string[], installed: string[], setup: object }>}
  */
 async function linkDependencyDirs({ mainCwd, worktreeCwd, names = DEFAULT_DEP_DIRS }) {
   const linked = [];
@@ -224,7 +225,17 @@ async function linkDependencyDirs({ mainCwd, worktreeCwd, names = DEFAULT_DEP_DI
       skipped.push(name);
     }
   }
-  return { linked, skipped, installed };
+  // Project warm-up (.session-manager.json worktreeSetup) runs after linking so it sees node_modules.
+  // Both createWorktree and the scheduler's verify scratch worktree come through here. mainCwd lets
+  // same-project setups serialize and reports a config missing from the worktree; the outcome is
+  // returned unchanged as `setup`. SM_WORKTREE_DEP_LINK_DISABLE=1 skips this at the gitWorktree.cjs call site.
+  let setup;
+  try {
+    setup = await runWorktreeSetup({ worktreeCwd, mainCwd });
+  } catch (err) {
+    setup = { ran: false, error: String(err && err.message) };
+  }
+  return { linked, skipped, installed, setup };
 }
 
 module.exports = { linkDependencyDirs, isPnpmProject, isUvProject, DEFAULT_DEP_DIRS };

package/src/main/lib/git/worktreeSetup.cjs

@@ -0,0 +1,212 @@
+/**
+ * worktreeSetup.cjs — run a project's one-time warm-up commands in a fresh
+ * worktree (e.g. Godot's first `--import` core-dumps; the second is clean).
+ *
+ * The project declares them in a TRACKED `.session-manager.json` at its root:
+ *   { "worktreeSetup": ["timeout 600 godot --headless --path game --import"] }
+ * Entries use gate syntax, are validated by prdGateFiles.validateGate, and run
+ * in order with cwd = the WORKTREE ROOT, so a project whose code lives in a
+ * subfolder names it itself (Godot's `--path game`).
+ *
+ * Execution: definitionOfDone.runIsolatedSequence — it never takes the shadow
+ * gate flag, so a setup is never skipped as "busy" and never makes a gate busy.
+ * Setups of the same project (key = path.resolve(mainCwd || worktreeCwd)) run
+ * strictly one at a time: a later call waits and is never skipped. Different
+ * projects run in parallel.
+ *
+ * Never throws. Always resolves to one outcome object:
+ *   { ran, ok, reason, error?, waitedMs, ms, commands }
+ *   commands: one { cmd, status, code, ms, timedOut, tail } per started command
+ *             (tail <= 1000 chars). ok is true only when every command passed.
+ *   reason when commands ran: 'passed' | 'failed' | 'unavailable'
+ *   reason otherwise: 'no-config' | 'not-in-worktree' | 'unreadable' |
+ *     'not-declared' | 'invalid' | 'opt-out' | 'no-commands' | 'error'
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { validateGate } = require('../prd/prdGateFiles.cjs');
+const { parseChain, runIsolatedSequence } = require('../scheduler/definitionOfDone.cjs');
+
+const CONFIG_NAME = '.session-manager.json';
+const TAIL_MAX = 1000;
+
+/** Per-project chain of in-flight setups; idle keys are deleted. */
+const setupChains = new Map();
+
+function log(msg) {
+  try { console.warn(`[worktreeSetup] ${msg}`); } catch { /* best-effort */ }
+}
+
+function skipped(reason, extra) {
+  return { ran: false, ok: false, reason, waitedMs: 0, ms: 0, commands: [], ...extra };
+}
+
+/** True when mainCwd's config declares a real (non-empty, non-"none") worktreeSetup. */
+function mainDeclaresSetup(mainCwd) {
+  if (typeof mainCwd !== 'string' || !mainCwd) return false;
+  try {
+    const cfg = JSON.parse(fs.readFileSync(path.join(mainCwd, CONFIG_NAME), 'utf8'));
+    const ws = cfg && cfg.worktreeSetup;
+    if (!Array.isArray(ws) || !ws.length) return false;
+    if (ws.length === 1 && typeof ws[0] === 'string' && /^none$/i.test(ws[0].trim())) return false;
+    return true;
+  } catch { return false; }
+}
+
+/**
+ * Resolve the sequence to run, or a skipped outcome.
+ * @returns {{ sequence: any[] } | { outcome: object }}
+ */
+function resolveConfig(worktreeCwd, mainCwd) {
+  let cfg;
+  try {
+    cfg = JSON.parse(fs.readFileSync(path.join(worktreeCwd, CONFIG_NAME), 'utf8'));
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      if (mainDeclaresSetup(mainCwd)) {
+        log(`${CONFIG_NAME} declares worktreeSetup in the main checkout but is not in this worktree's commit — commit it`);
+        return { outcome: skipped('not-in-worktree') };
+      }
+      return { outcome: skipped('no-config') };
+    }
+    const msg = String(err && err.message);
+    log(`${CONFIG_NAME} unreadable, setup skipped: ${msg}`);
+    return { outcome: skipped('unreadable', { error: msg }) };
+  }
+  if (!cfg || typeof cfg !== 'object' || !('worktreeSetup' in cfg)) return { outcome: skipped('not-declared') };
+  if (!Array.isArray(cfg.worktreeSetup)) {
+    const error = 'worktreeSetup must be an array of gate-syntax strings';
+    log(`invalid worktreeSetup, skipped: ${error}`);
+    return { outcome: skipped('invalid', { error }) };
+  }
+  const v = validateGate(cfg.worktreeSetup);
+  if (!v.ok) {
+    log(`invalid worktreeSetup, skipped: ${v.error}`);
+    return { outcome: skipped('invalid', { error: v.error }) };
+  }
+  if (v.commands.length === 1 && /^none$/i.test(v.commands[0])) return { outcome: skipped('opt-out') };
+  const sequence = [];
+  for (const chain of v.commands) sequence.push(...parseChain(chain));
+  if (!sequence.length) return { outcome: skipped('no-commands') };
+  return { sequence };
+}
+
+async function execute(sequence, worktreeCwd, startedAt) {
+  const t0 = Date.now();
+  const res = await runIsolatedSequence(sequence, { cwd: worktreeCwd });
+  const results = Array.isArray(res.results) ? res.results : [];
+  const commands = results.map((r, i) => ({
+    cmd: sequence[i]?.raw ?? r.cmd,
+    status: r.status,
+    code: r.code,
+    ms: r.ms,
+    timedOut: r.timedOut,
+    tail: typeof r.tail === 'string' ? r.tail.slice(-TAIL_MAX) : r.tail,
+  }));
+  const reason = res.status === 'green' ? 'passed' : res.status === 'red' ? 'failed' : 'unavailable';
+  if (reason !== 'passed') {
+    const last = commands[commands.length - 1] || {};
+    log(`setup ${reason}: ${last.cmd ?? '(no command started)'} (exit ${last.code ?? 'n/a'}, ${last.status ?? res.status})`);
+  }
+  return {
+    ran: commands.length > 0,
+    ok: reason === 'passed',
+    reason,
+    waitedMs: t0 - startedAt,
+    ms: Date.now() - t0,
+    commands,
+  };
+}
+
+/**
+ * @param {{ worktreeCwd: string, mainCwd?: string }} opts
+ * @returns {Promise<{ ran: boolean, ok: boolean, reason: string, error?: string, waitedMs: number, ms: number, commands: object[] }>}
+ */
+async function runWorktreeSetup(opts) {
+  try {
+    const { worktreeCwd, mainCwd } = opts || {};
+    if (typeof worktreeCwd !== 'string' || !worktreeCwd) return skipped('no-config');
+    const cfg = resolveConfig(worktreeCwd, mainCwd);
+    if (cfg.outcome) return cfg.outcome;
+
+    const key = path.resolve(mainCwd || worktreeCwd);
+    const startedAt = Date.now();
+    const prev = setupChains.get(key) || Promise.resolve();
+    const mine = prev.catch(() => {}).then(() => execute(cfg.sequence, worktreeCwd, startedAt));
+    setupChains.set(key, mine);
+    try {
+      return await mine;
+    } finally {
+      if (setupChains.get(key) === mine) setupChains.delete(key);
+    }
+  } catch (err) {
+    const error = String(err && err.message);
+    log(`unexpected error: ${error}`);
+    return skipped('error', { error });
+  }
+}
+
+const LINE_PREFIX = '[scheduler] worktree setup:';
+const LINE_MAX = 500;
+/** Reasons that mean "nothing to log" (no setup applies). */
+const SILENT_REASONS = new Set(['no-config', 'in-place']);
+/** Skip reasons where the worktree is still trustworthy for a gate. */
+const SETTLED_REASONS = new Set(['no-config', 'not-declared', 'opt-out']);
+
+function clip(line) {
+  return line.length <= LINE_MAX ? line : `${line.slice(0, LINE_MAX - 1)}…`;
+}
+const secs = (ms) => (Math.round((Number(ms) || 0) / 100) / 10).toString();
+
+/**
+ * Run-log lines for a setup outcome. Pure; never throws. Lines are
+ * `[scheduler]`-prefixed and never carry command output (tails stay in
+ * meta.json) so the run-log detectors cannot be tripped by a setup command.
+ * @param {any} outcome
+ * @returns {string[]}
+ */
+function formatSetupOutcome(outcome) {
+  try {
+    if (!outcome || typeof outcome !== 'object') return [];
+    const reason = String(outcome.reason);
+    if (SILENT_REASONS.has(reason)) return [];
+    if (!outcome.ran) {
+      let line = `${LINE_PREFIX} skipped — ${reason}`;
+      if (outcome.error) line += `: ${String(outcome.error)}`;
+      const lines = [clip(line)];
+      if (reason === 'not-in-worktree') {
+        lines.push(clip(`${LINE_PREFIX} .session-manager.json is in the main checkout but not in this worktree's commit`));
+      }
+      return lines;
+    }
+    const commands = Array.isArray(outcome.commands) ? outcome.commands : [];
+    let summary = `${LINE_PREFIX} ${reason} — ${commands.length} command(s) in ${secs(outcome.ms)}s`;
+    if (Number(outcome.waitedMs) >= 1000) summary += `, waited ${secs(outcome.waitedMs)}s`;
+    const lines = [clip(summary)];
+    for (const c of commands) {
+      const cc = c && typeof c === 'object' ? c : {};
+      const code = cc.code === null || cc.code === undefined ? 'n/a' : String(cc.code);
+      lines.push(clip(`${LINE_PREFIX}   exit ${code} in ${Number(cc.ms) || 0}ms${cc.timedOut ? ', timed out' : ''}: ${String(cc.cmd ?? '')}`));
+    }
+    if (outcome.ok === false) {
+      lines.push(clip(`${LINE_PREFIX} output tail is in the run's meta.json under worktreeSetup.commands[].tail`));
+    }
+    return lines;
+  } catch { return []; }
+}
+
+/**
+ * True when a gate can trust the worktree: setup passed, or none is declared.
+ * @param {any} outcome
+ * @returns {boolean}
+ */
+function isSetupSettled(outcome) {
+  try {
+    if (!outcome || typeof outcome !== 'object') return false;
+    return outcome.ok === true || SETTLED_REASONS.has(outcome.reason);
+  } catch { return false; }
+}
+
+module.exports = { runWorktreeSetup, formatSetupOutcome, isSetupSettled, CONFIG_NAME };

package/src/main/lib/mcpToolCatalog.cjs

@@ -107,8 +107,9 @@ const MCP_TOOL_CATALOG = [
       + 'no shell metacharacters), or exactly `["none"]` for a PRD with no runnable check; the scheduler '
       + 're-runs these commands and reads them back from the rendered `# Gate` section verbatim, so a stray '
       + '```gate fence anywhere else in the PRD text is rejected. `files` lists the 1-50 repo-relative files '
-      + 'or folders this PRD may change; PRDs that can run at the same time must not share a file — chain '
-      + 'them with `dependsOn` instead.',
+      + 'or folders this PRD may change; The scheduler never runs two PRDs with overlapping files at once '
+      + '(dispatch holds the later one), so `dependsOn` is for real output or order dependencies, not for '
+      + 'avoiding file clashes.',
     whenToUse: 'Use whenever new work should be queued into an already-approved Epic — this is the /develop path.',
     whenNotToUse: 'TWO DISTINCT FAILURE MODES if this tool is not usable — do not conflate them: '
       + '(a) this tool call is PRESENT in your tool list but ERRORS — NEVER hand-write a PRD file. '
@@ -134,6 +135,34 @@ const MCP_TOOL_CATALOG = [
     },
     notes: 'See /develop.',
   },
+  {
+    name: 'scheduler_create_prds',
+    group: 'scheduler',
+    purpose: 'Write a whole plan of PRDs in ONE all-or-nothing call (1 to 40 entries) via the session-manager '
+      + "app's admin API. Each entry is exactly a scheduler_create_prd input (gate and files REQUIRED per entry). "
+      + 'Every entry is validated first; only if all pass are NNs allocated and files written, otherwise NOTHING is '
+      + 'written and every per-entry error is returned as { index, slug, error }. Returns each slug and its NN, plus '
+      + 'any advisory warnings. Like scheduler_create_prd it only writes files; the queue rows are derived by the '
+      + 'next reconcile pass. All entries must resolve to the same project and Epic; top-level cwd, sourcePromptId '
+      + 'and origin fields are forwarded the same way as scheduler_create_prd.',
+    whenToUse: 'Use to queue a whole plan at once, validate PRD included: dependsOn may name other entries of the same call by bare slug (earlier or later), so a chain needs no ordering of calls.',
+    whenNotToUse: 'Do not use for a single PRD — use scheduler_create_prd. Not callable from inside a headless scheduled job (same refusal as scheduler_create_prd). If the app is not running, stop and ask the human to start it; never hand-write PRD files.',
+    exampleArgs: {
+      prds: [
+        {
+          title: 'Add retry backoff helper',
+          goal: 'Add retryWithBackoff.cjs.',
+          acceptanceCriteria: ['Helper exists', 'Unit tests pass'],
+          implementationNotes: 'See existing helpers under src/main/lib/.',
+          gate: ['timeout 300 npm run test:unit'],
+          files: ['src/main/lib/retryWithBackoff.cjs'],
+          slug: 'add-retry-backoff',
+          sourcePromptId: 'epic-id-of-an-already-approved-session',
+        },
+      ],
+    },
+    notes: 'See /develop.',
+  },
   {
     name: 'scheduler_list_prds',
     group: 'scheduler',

package/src/main/lib/persona-macro/agentPersonaSchema.cjs

@@ -58,6 +58,8 @@ const AgentPersonaSaveSchema = z.object({
   tools: z.array(BoundedString),
   model: BoundedString,
   effort: BoundedString.optional(),
+  // Wall-clock budget default for PRDs without estimateMinutes (60 × factor 3 reaches the 180-min ceiling).
+  defaultEstimateMinutes: z.number().int().min(1).max(60).optional(),
   color: BoundedString,
   // A legacy tag value (e.g. the retired 'bilko-host-publisher') must keep
   // loading on an old on-disk persona — dropped silently, never thrown. Any
@@ -77,6 +79,8 @@ const AgentPersonaSaveSchema = z.object({
   // Without this field zod's default "strip unknown keys" behavior would
   // silently drop it from a save payload that did carry one.
   seedVersion: z.number().int().optional(),
+  // Executor-only persona (e.g. dev-lead): New Epic warns when picked as the planning Actor. Never blocks.
+  executorOnly: z.boolean().optional(),
   // Unbounded — a persona's body is arbitrary system-prompt prose.
   body: z.string(),
 });

package/src/main/lib/persona-macro/shippedPersonaSeeds.cjs

@@ -135,6 +135,18 @@ const SHIPPED_PERSONA_SEEDS = deepFreeze({
         tools: "Read, Grep, Glob, Bash, Edit, Write",
       },
     },
+    {
+      commit: "9e400786",
+      bodySha256: "82b93c1da9a5e3b7dfcfadd1b4689d988a4bd19de2d897ebd3f3158969d741fc",
+      fm: {
+        description: "Executes exactly one already-scoped PRD at a time, headless, start to finish — reads the PRD's Goal/Acceptance Criteria/Implementation notes and standards.md, implements it, verifies against its own AC, and reports. Has no visibility into the overall plan — that's architect's job. This is the default persona a scheduled PRD runs as: the scheduler resolves a PRD's `agentType` frontmatter field (default `dev-lead`) to this file and launches the headless executor AS this persona via `--append-system-prompt`.",
+        effort: "medium",
+        executorOnly: "true",
+        model: "sonnet",
+        title: "Engineering — Software Engineer",
+        tools: "Read, Grep, Glob, Bash, Edit, Write",
+      },
+    },
   ],
   "project-home-builder": [
     {
@@ -228,6 +240,17 @@ const SHIPPED_PERSONA_SEEDS = deepFreeze({
         tools: "Read, Grep, Glob, Bash",
       },
     },
+    {
+      commit: "9e400786",
+      bodySha256: "ca159cd47ac4b618af842c6ccd59107fac4a34b0efcfa5dfe7d06875736156ed",
+      fm: {
+        description: "Validates a finished PLAN (the PRDs its validate PRD lists) once, after its last PRD lands — re-runs each PRD's gate, checks every acceptance criterion against the real tree, reviews the plan's combined diff, and reports one VERIFIED/REFUTED verdict per PRD via sentinel lines. Runs headless as a scheduled PRD (agentType: validator); never edits product code and never queues work.",
+        executorOnly: "true",
+        model: "sonnet",
+        title: "Engineering — Plan Validator",
+        tools: "Read, Grep, Glob, Bash",
+      },
+    },
   ],
   "demo-video-builder": [
     {

package/src/main/lib/prd/prdAgentType.cjs

@@ -15,6 +15,8 @@
 
 const { personaFileExists, resolvePersonaPaths } = require('../epic/epicMint.cjs');
 const { listPersonas } = require('../../agentLibrary.cjs');
+const { splitFrontmatter } = require('./prdFrontmatter.cjs');
+const fs = require('node:fs');
 
 /** PRD execution's documented default persona (dev-lead.md's own frontmatter role). */
 const DEFAULT_PRD_AGENT_TYPE = 'dev-lead';
@@ -77,8 +79,34 @@ async function assertAgentTypeWritable(cwd, agentType, deps = {}) {
   );
 }
 
+/**
+ * resolvePersonaDefaultEstimate(cwd, agentType, deps) — the persona's
+ * optional `defaultEstimateMinutes` frontmatter (integer 1..60), project
+ * overlay before global. Returns a number or null; never throws (missing,
+ * malformed or out-of-range → null). Uncached sync read: called once per
+ * job spawn.
+ */
+function resolvePersonaDefaultEstimate(cwd, agentType, deps = {}) {
+  try {
+    if (!cwd || typeof agentType !== 'string' || !/^[a-z0-9][a-z0-9-]*$/.test(agentType)) return null;
+    const { projectPath, globalPath } = resolvePersonaPaths(cwd, agentType, deps);
+    for (const file of [projectPath, globalPath]) {
+      let text;
+      try { text = fs.readFileSync(file, 'utf8'); } catch { continue; }
+      const raw = splitFrontmatter(text).fm.defaultEstimateMinutes;
+      if (raw === undefined) continue;
+      const str = String(raw).trim();
+      if (!/^\d+$/.test(str)) continue;
+      const n = Number(str);
+      if (n >= 1 && n <= 60) return n;
+    }
+  } catch { /* never throws */ }
+  return null;
+}
+
 module.exports = {
   DEFAULT_PRD_AGENT_TYPE,
+  resolvePersonaDefaultEstimate,
   assertAgentTypeWritable,
   reportDanglingAgentTypeOnce,
 };