claude-code-session-manager 0.120.0 → 0.122.0

package/src/main/lib/claude/effectiveModelInfo.cjs

@@ -137,28 +137,16 @@ function readHotJobsForCwd(cwd, deps) {
 /** Best-effort read of `<cwd>/session-manager-operations/scheduler/state/history.jsonl`'s archived rows. */
 function readHistoryEntriesForCwd(cwd, deps) {
   const { projectHistoryPath } = deps.queueStore || require('../scheduler/queueStore.cjs');
-  let text;
-  try {
-    text = fs.readFileSync(projectHistoryPath(cwd), 'utf8');
-  } catch {
-    return [];
-  }
+  const { readHistoryFileTailSync } = deps.queueHistory || require('../scheduler/queueHistory.cjs');
+  // Bounded tail (<=500 rows / <=1 MB): only the most recent matching row matters.
+  const rows = readHistoryFileTailSync(projectHistoryPath(cwd), { maxRows: 500, maxBytes: 1024 * 1024 });
+  // Tail reader is newest-first; callers sort by timestamp anyway.
   const entries = [];
-  for (const line of text.split('\n')) {
-    if (!line.trim()) continue;
-    try {
-      const j = JSON.parse(line);
-      // needs_review_entry/needs_review_resolution lines (needsReviewLedger.cjs)
-      // share history.jsonl with terminal job rows but carry no `agentType` —
-      // findLatestSchedulerModel's own `j.agentType === agentType` filter
-      // already excludes them, but skip explicitly here too so this reader
-      // stays correct even if a future ledger line shape happens to pick up
-      // an agentType-shaped field.
-      if (j?.kind && j.kind !== 'terminal') continue;
-      entries.push(j);
-    } catch {
-      // corrupt/partial line — skip
-    }
+  for (const j of rows) {
+    // needs_review_entry/needs_review_resolution lines (needsReviewLedger.cjs)
+    // share history.jsonl with terminal job rows; skip non-terminal kinds.
+    if (j?.kind && j.kind !== 'terminal') continue;
+    entries.push(j);
   }
   return entries;
 }

package/src/main/lib/claude/personaToolScope.cjs

@@ -54,10 +54,16 @@ function personaToolScopeArgs(scope) {
     prompt: 'Tool scope is enforced by the scheduler.',
     tools: scope.tools,
   };
-  return [
+  const args = [
     '--agents', JSON.stringify({ [HEADLESS_SCOPE_AGENT_NAME]: def }),
     '--agent', HEADLESS_SCOPE_AGENT_NAME,
   ];
+  // A scope naming no MCP tool never uses a server: with --strict-mcp-config and
+  // no --mcp-config (variadic; would swallow later args) the CLI boots none.
+  if (!scope.tools.some((t) => String(t).startsWith('mcp__'))) {
+    args.push('--strict-mcp-config');
+  }
+  return args;
 }
 
 module.exports = {

package/src/main/lib/claude/runClaudeP.cjs

@@ -32,6 +32,7 @@ async function runClaudeP(prompt, { model = 'sonnet', timeoutMs = 180_000, syste
       '--model', model,
       '--dangerously-skip-permissions',
       ...headlessPermissionArgs(),
+      '--strict-mcp-config',
       '--output-format', 'text',
     ];
     if (systemPrompt) args.push('--append-system-prompt', systemPrompt);

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

@@ -303,18 +303,84 @@ async function checkSchedulerMcpLive({ cwd, homeDir, schedulerMcpCheck }) {
   };
 }
 
+const DEV_PLUGIN_MARKETPLACE = 'session-manager';
+const DEV_PLUGIN_REINSTALL_FIX = 'Restart Session Manager to reinstall the session-manager-dev plugin';
+
+/** installPath of the dev plugin from installed_plugins.json, or null. */
+function readDevPluginInstallPath(homeDir) {
+  const data = readJsonOrSync(path.join(homeDir, '.claude', 'plugins', 'installed_plugins.json'), null);
+  const entries = data?.plugins?.[DEV_PLUGIN_ENABLED_KEY];
+  if (!Array.isArray(entries)) return null;
+  for (const e of entries) {
+    if (e && typeof e.installPath === 'string' && e.installPath) return e.installPath;
+  }
+  return null;
+}
+
+/** Source path of the 'session-manager' marketplace from known_marketplaces.json, or null. */
+function readDevMarketplacePath(homeDir) {
+  const data = readJsonOrSync(path.join(homeDir, '.claude', 'plugins', 'known_marketplaces.json'), null);
+  const m = data?.[DEV_PLUGIN_MARKETPLACE];
+  const p = m?.source?.path ?? m?.installLocation;
+  return typeof p === 'string' && p ? p : null;
+}
+
 function checkDevPlugin({ homeDir }) {
   const settings = readJsonOrSync(path.join(homeDir, '.claude', 'settings.json'), null);
-  const ok = settings?.enabledPlugins?.[DEV_PLUGIN_ENABLED_KEY] === true;
+  const enabled = settings?.enabledPlugins?.[DEV_PLUGIN_ENABLED_KEY] === true;
+  const base = { id: 'dev-plugin', label: 'session-manager-dev plugin enabled' };
+
+  if (!enabled) {
+    return {
+      ...base,
+      ok: false,
+      detail: `${DEV_PLUGIN_ENABLED_KEY} missing from ~/.claude/settings.json enabledPlugins`,
+      fix: 'Enable in Plugins tab: session-manager-dev (Session Manager)',
+    };
+  }
+
+  const installPath = readDevPluginInstallPath(homeDir);
+  if (!installPath) {
+    return {
+      ...base,
+      ok: false,
+      detail: `${DEV_PLUGIN_ENABLED_KEY} enabled but not recorded in ~/.claude/plugins/installed_plugins.json`,
+      fix: DEV_PLUGIN_REINSTALL_FIX,
+    };
+  }
+  const skillFile = path.join(installPath, 'skills', 'develop', 'SKILL.md');
+  if (!fs.existsSync(skillFile)) {
+    return {
+      ...base,
+      ok: false,
+      detail: `${DEV_PLUGIN_ENABLED_KEY} enabled but ${skillFile} is missing`,
+      fix: DEV_PLUGIN_REINSTALL_FIX,
+    };
+  }
+
+  const marketplacePath = readDevMarketplacePath(homeDir);
+  if (!marketplacePath) {
+    return {
+      ...base,
+      ok: false,
+      detail: `'${DEV_PLUGIN_MARKETPLACE}' marketplace not registered in ~/.claude/plugins/known_marketplaces.json`,
+      fix: DEV_PLUGIN_REINSTALL_FIX,
+    };
+  }
+  if (!fs.existsSync(marketplacePath)) {
+    return {
+      ...base,
+      ok: false,
+      detail: `'${DEV_PLUGIN_MARKETPLACE}' marketplace folder ${marketplacePath} no longer exists`,
+      fix: DEV_PLUGIN_REINSTALL_FIX,
+    };
+  }
 
   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)',
+    ...base,
+    ok: true,
+    detail: `${DEV_PLUGIN_ENABLED_KEY} enabled in ~/.claude/settings.json and installed on disk`,
+    fix: null,
   };
 }
 
@@ -795,6 +861,7 @@ async function ensureGuardsInstalled(cwd, { homeDir = os.homedir() } = {}) {
 }
 
 module.exports = {
+  checkDevPlugin,
   checkDelegationReadiness,
   ensureGuardsInstalled,
   logAutoInstallEvent,

package/src/main/lib/mcpToolCatalog.cjs

@@ -127,7 +127,6 @@ const MCP_TOOL_CATALOG = [
     exampleArgs: {
       title: 'Add unit tests for the retry backoff helper',
       cwd: '/home/bilko/Projects/session-manager',
-      estimateMinutes: 10,
       goal: 'Cover retryWithBackoff.cjs edge cases (zero retries, max-delay clamp) that currently have no test.',
       acceptanceCriteria: ['New test file exercises zero-retry and max-delay-clamp cases', 'Typecheck passes', 'Unit tests pass'],
       implementationNotes: 'See src/main/lib/retryWithBackoff.cjs and its existing __tests__ sibling for the pattern to extend.',

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

@@ -93,6 +93,61 @@ function refineInputs(value, ctx) {
   }
 }
 
+/** Distinct `{{name}}` placeholder names in first-seen order. */
+function macroPlaceholders(prompt) {
+  const names = [];
+  for (const m of String(prompt).matchAll(new RegExp(MACRO_PLACEHOLDER_RE.source, 'g'))) {
+    if (!names.includes(m[1])) names.push(m[1]);
+  }
+  return names;
+}
+
+/** `{ [name]: default ?? '' }` for every declared input. */
+function defaultMacroValues(inputs) {
+  const out = {};
+  for (const i of inputs || []) out[i.name] = i.default ?? '';
+  return out;
+}
+
+function sanitizeMacroValue(v) {
+  // eslint-disable-next-line no-control-regex
+  return v.replace(/[\r\n\t]+/g, ' ').replace(/[\u0000-\u001f\u007f]/g, '').trim();
+}
+
+const MACRO_PROMPT_RENDERED_MAX_LEN = 8000;
+
+/**
+ * Mirrors `src/renderer/lib/macroPrompt.ts` renderMacroPrompt, but strict for macros
+ * without inputs: a placeholder with no declared input is always an error.
+ * @returns {{ ok: true, prompt: string } | { ok: false, error: string }}
+ */
+function renderMacroPrompt(prompt, inputs, values) {
+  const vals = values && typeof values === 'object' ? values : {};
+  const clean = Object.create(null);
+  for (const input of inputs || []) {
+    const own = Object.prototype.hasOwnProperty.call(vals, input.name) && typeof vals[input.name] === 'string';
+    const v = sanitizeMacroValue(own ? vals[input.name] : (input.default ?? ''));
+    if (v === '') {
+      if (input.required) return { ok: false, error: `"${input.label}" is required` };
+    } else if (v.length > MACRO_INPUT_MAX_LEN) {
+      return { ok: false, error: `"${input.label}" is longer than ${MACRO_INPUT_MAX_LEN} characters` };
+    } else if (input.options && input.options.length > 0 && !input.options.includes(v)) {
+      return { ok: false, error: `"${input.label}" must be one of: ${input.options.join(', ')}` };
+    }
+    clean[input.name] = v;
+  }
+
+  for (const name of macroPlaceholders(prompt)) {
+    if (!(name in clean)) return { ok: false, error: `prompt uses undeclared input {{${name}}}` };
+  }
+
+  const rendered = String(prompt).replace(new RegExp(MACRO_PLACEHOLDER_RE.source, 'g'), (_m, n) => clean[n]);
+  if (rendered.length > MACRO_PROMPT_RENDERED_MAX_LEN) {
+    return { ok: false, error: `rendered prompt is longer than ${MACRO_PROMPT_RENDERED_MAX_LEN} characters` };
+  }
+  return { ok: true, prompt: rendered };
+}
+
 const MacroSchema = z.object({
   id: MacroIdSchema,
   label: MacroLabelSchema,
@@ -151,6 +206,12 @@ function normalizeCwd(cwd) {
   return collapsed.replace(/\/+$/, '');
 }
 
+/** True iff the macro is shown for `cwd`: its projects include '*' or the normalized cwd. */
+function macroVisibleIn(macro, cwd) {
+  const projects = (macro && macro.projects) || [];
+  return projects.includes(ALL_PROJECTS) || projects.includes(normalizeCwd(cwd));
+}
+
 function normalizeProjects(projects) {
   const out = [];
   for (const p of projects || []) {
@@ -414,6 +475,14 @@ async function loadForWrite(filePath, opts) {
  * Create (no id) or update (id) a macro. Returns the saved Macro.
  * Throws on invalid input or unknown id.
  */
+/** Merged-macro check: every `{{name}}` in the prompt must be a declared input. */
+function assertPlaceholdersDeclared(macro) {
+  const declared = new Set((macro.inputs || []).map((i) => i.name));
+  for (const name of macroPlaceholders(macro.prompt)) {
+    if (!declared.has(name)) throw new Error(`prompt placeholder {{${name}}} is not declared in inputs`);
+  }
+}
+
 async function saveMacro(input, opts = {}) {
   const parsed = MacroSaveSchema.parse(input);
   const filePath = resolvePath(opts);
@@ -442,6 +511,7 @@ async function saveMacro(input, opts = {}) {
       } else {
         saved.inputs = parsed.inputs;
       }
+      assertPlaceholdersDeclared(saved);
       macros[idx] = saved;
     } else {
       const projects = parsed.projects !== undefined ? normalizeProjects(parsed.projects) : [];
@@ -457,6 +527,7 @@ async function saveMacro(input, opts = {}) {
         updatedAt: now,
       };
       if (parsed.inputs && parsed.inputs.length > 0) saved.inputs = parsed.inputs;
+      assertPlaceholdersDeclared(saved);
       macros.push(saved);
     }
     await writeStore(filePath, macros);
@@ -518,6 +589,10 @@ module.exports = {
   MacroSaveSchema,
   MacroDeleteSchema,
   MacroSetProjectSchema,
+  macroPlaceholders,
+  defaultMacroValues,
+  renderMacroPrompt,
+  macroVisibleIn,
   listMacros,
   saveMacro,
   deleteMacro,

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

@@ -124,6 +124,17 @@ const SHIPPED_PERSONA_SEEDS = deepFreeze({
         tools: "Read, Grep, Glob, Bash, Edit, Write",
       },
     },
+    {
+      commit: "2129verify",
+      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`.",
+        model: "sonnet",
+        effort: "medium",
+        title: "Engineering — Software Engineer",
+        tools: "Read, Grep, Glob, Bash, Edit, Write",
+      },
+    },
   ],
   "project-home-builder": [
     {

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

@@ -29,6 +29,7 @@ const { resolveProjectContext } = require('../projectRootResolve.cjs');
 const { fixChainDepthOf, baseSlugOf } = require('../scheduler/fixChainDepth.cjs');
 const { DEFAULT_PRD_AGENT_TYPE, assertAgentTypeWritable } = require('./prdAgentType.cjs');
 const { resolveDepSlug, findNearMatches } = require('./depSlugResolve.cjs');
+const { resolveEpicPrdWriteDir } = require('./prdLocations.cjs');
 const { isFixPlanSlug } = require('../scheduler/fixPlanSlug.cjs');
 const { isIncomplete, resolveChainTerminals, isValidPlanId, mintPlanId, resolveInheritedPlanId } = require('./prdDisposition.cjs');
 const { sizingWarnings } = require('./prdSizing.cjs');
@@ -87,7 +88,9 @@ function buildPrdBody(input) {
   // No `parallelGroup` frontmatter key (PRD_AUTHORING.md §5) — the NN-
   // filename prefix is the single source of truth for grouping; adding a
   // second one here would let the two drift out of sync.
-  const fmLines = ['---', `title: ${title}`, `cwd: ${cwd}`, `estimateMinutes: ${estimateMinutes}`];
+  const fmLines = ['---', `title: ${title}`, `cwd: ${cwd}`];
+  // Optional: only a finite positive integer is written; absent => budget's 45-min floor.
+  if (Number.isInteger(estimateMinutes) && estimateMinutes > 0) fmLines.push(`estimateMinutes: ${estimateMinutes}`);
   // Provenance stamp (PRD-authoring lockdown): every PRD written through this
   // function — the sole in-process implementation behind both the admin
   // HTTP create-prd route and the renderer's chat:create-prd IPC handler —
@@ -443,6 +446,30 @@ async function createPrd(input, remote) {
   }
   extraWarnings.push(...await worktreeReachAdvisory(input, cwd));
 
+  // Duplicate-slug guard (2110/2111 phone-drop-summary-state: duplicate re-issue after archive).
+  // Finished rows leave queue.json, so an author can re-issue a landed PRD under a fresh NN.
+  // Refused before NN allocation so it burns no number. Fix plans are exempt.
+  if (input.sourcePromptId && !isFixPlanSlug(`0-${slug}`)) {
+    let epicDirs = [];
+    try {
+      const prdsDir = resolveEpicPrdWriteDir(cwd, input.sourcePromptId);
+      epicDirs = [prdsDir, path.join(path.dirname(prdsDir), 'prds-archived')];
+    } catch { /* unsafe epic id — no dirs to scan */ }
+    for (const dir of epicDirs) {
+      let names = [];
+      try { names = await fsp.readdir(dir); } catch { /* missing dir counts as empty */ }
+      const dup = names.find((n) => n.endsWith('.md') && n.slice(0, -3).replace(/^\d+-/, '') === slug);
+      if (dup) {
+        return {
+          ok: false,
+          status: 409,
+          error: `A PRD with slug "${slug}" already exists in this Epic as "${dup}". Its work may already have landed. ` +
+            'Use scheduler_update_prd / scheduler_reset_job on it, or pick a distinct slug.',
+        };
+      }
+    }
+  }
+
   const nn = await remote.allocateParallelGroup(input.cwd);
   const filenameSlug = `${nn}-${slug}`;
 

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

@@ -11,7 +11,6 @@
 'use strict';
 
 const SIZING_LIMITS = {
-  estimateMinutes: 15,
   acLines: 8,
   acLineChars: 400,
   bodyChars: 7000,
@@ -30,18 +29,12 @@ const TIMEOUT_CMD_RE = /\btimeout\s+\d+/gi;
  * treated as empty/absent rather than thrown on, since this is advisory only.
  */
 function sizingWarnings(input) {
-  const { estimateMinutes, goal, implementationNotes } = input || {};
+  const { goal, implementationNotes } = input || {};
   const acceptanceCriteria = Array.isArray(input?.acceptanceCriteria) ? input.acceptanceCriteria : [];
   const acLines = acceptanceCriteria.filter((line) => typeof line === 'string');
 
   const warnings = [];
 
-  if (typeof estimateMinutes === 'number' && estimateMinutes > SIZING_LIMITS.estimateMinutes) {
-    warnings.push(
-      `estimateMinutes (${estimateMinutes}) exceeds the ${SIZING_LIMITS.estimateMinutes}-minute sizing limit — split this PRD into smaller work items.`,
-    );
-  }
-
   if (acceptanceCriteria.length > SIZING_LIMITS.acLines) {
     warnings.push(
       `acceptanceCriteria has ${acceptanceCriteria.length} lines, exceeding the ${SIZING_LIMITS.acLines}-line sizing limit — split into smaller, single-purpose PRDs.`,

package/src/main/lib/remoteTranscriptTail.cjs

@@ -2,6 +2,7 @@
 
 // Bounded-tail reader for Claude Code JSONL transcripts: the last N human-readable
 // chat messages (user prompts + assistant text) without reading the whole file.
+// Also builds the phone's conversation page (exchanges + live tail) in pure code.
 // Top-level (no domain fits: epic/ transcripts are path-only; util/ is domain-free).
 // Transcripts reach hundreds of MB, so cost is O(maxBytes), never O(file).
 
@@ -11,6 +12,10 @@ const DEFAULT_LIMIT = 30;
 const MAX_LIMIT = 100;
 const DEFAULT_MAX_BYTES = 524288;
 const MAX_TEXT_CHARS = 4000;
+const MAX_PROMPT_CHARS = 2000;
+const MAX_RESULT_CHARS = 16000;
+const MAX_LIVE_MESSAGES = 20;
+const MAX_PAGE_TEXT_BYTES = 100000; // relay closes any message over 256 KB
 
 /** Join the plain-text parts of a message `content` (string or block array). */
 function textOf(content) {
@@ -22,8 +27,12 @@ function textOf(content) {
     .join('\n');
 }
 
+function cap(text, max) {
+  return text.length > max ? text.slice(0, max - 1) + '…' : text;
+}
+
 function truncate(text) {
-  return text.length > MAX_TEXT_CHARS ? text.slice(0, MAX_TEXT_CHARS - 1) + '…' : text;
+  return cap(text, MAX_TEXT_CHARS);
 }
 
 /** Parse one JSONL line into a chat message, or null when it is not one. */
@@ -87,4 +96,62 @@ async function readRecentChatMessages(filePath, { limit = DEFAULT_LIMIT, maxByte
   }
 }
 
-module.exports = { readRecentChatMessages };
+/**
+ * Pure: build one phone-ready conversation page from exchanges (NEWEST-FIRST,
+ * callers fetch `limit + 1` so `hasMore` is derivable) plus the live transcript tail.
+ * @param {{ exchanges?: any[], tail?: any[], limit?: number, before?: number }} [opts]
+ * @returns {{ messages: Array<{ role: string, text: string, ts: string|null, uuid: string|null, live?: true }>, hasMore: boolean, nextBefore: number|null }}
+ *   messages oldest-first: history, then live.
+ */
+function buildRemoteConversation({ exchanges = [], tail = [], limit = 10, before = 0 } = {}) {
+  const n = Math.floor(Number(limit));
+  const lim = Number.isFinite(n) && n >= 1 ? n : 10;
+  const b = Math.max(0, Math.floor(Number(before)) || 0);
+  const valid = (Array.isArray(exchanges) ? exchanges : []).filter((e) => e && typeof e === 'object' && typeof e.ts === 'string');
+  const candidates = valid.slice(0, lim);
+  let hasMore = valid.length > lim;
+  let budget = MAX_PAGE_TEXT_BYTES;
+  const size = (text) => Buffer.byteLength(text, 'utf8');
+
+  // Live tail (first page only): newest-first until the budget is hit.
+  const live = [];
+  if (b === 0 && Array.isArray(tail)) {
+    const newest = valid.reduce((m, e) => Math.max(m, Date.parse(e.ts) || 0), 0);
+    const fresh = tail.filter((m) => {
+      if (!m || typeof m !== 'object' || typeof m.text !== 'string') return false;
+      if (!valid.length) return true;
+      const t = typeof m.ts === 'string' ? Date.parse(m.ts) : NaN;
+      return Number.isFinite(t) && t > newest;
+    });
+    for (const m of fresh.slice(-MAX_LIVE_MESSAGES).reverse()) {
+      const bytes = size(m.text);
+      if (bytes > budget) break;
+      budget -= bytes;
+      live.push({ role: m.role, text: m.text, ts: m.ts ?? null, uuid: m.uuid ?? null, live: true });
+    }
+    live.reverse();
+  }
+
+  // History: whole exchanges newest-first, oldest dropped when over budget.
+  const history = [];
+  let returned = 0;
+  for (const e of candidates) {
+    const pair = [];
+    const prompt = typeof e.prompt === 'string' ? e.prompt.trim() : '';
+    const result = typeof e.result === 'string' ? e.result.trim() : '';
+    if (prompt) pair.push({ role: 'user', text: cap(prompt, MAX_PROMPT_CHARS), ts: e.ts, uuid: `ex:${e.ts}:u` });
+    if (result) pair.push({ role: 'assistant', text: cap(result, MAX_RESULT_CHARS), ts: e.ts, uuid: `ex:${e.ts}:a` });
+    const bytes = pair.reduce((s, m) => s + size(m.text), 0);
+    if (bytes > budget) {
+      hasMore = true;
+      break;
+    }
+    budget -= bytes;
+    history.unshift(...pair);
+    returned++;
+  }
+
+  return { messages: [...history, ...live], hasMore, nextBefore: hasMore ? b + returned : null };
+}
+
+module.exports = { readRecentChatMessages, buildRemoteConversation };

package/src/main/lib/runSeeders.cjs

@@ -0,0 +1,21 @@
+// Runs first-boot seeders one at a time. `claude plugin install` and
+// `claude mcp add --scope user` both rewrite Claude's config files; run
+// concurrently, one write can drop the other's entry after its marker says done.
+// A failing step is logged and never skips the steps after it.
+
+/**
+ * @param {Array<{ name: string, run: () => Promise<unknown> }>} steps
+ * @returns {Promise<void>}
+ */
+async function runSeedersSerially(steps) {
+  for (const step of steps) {
+    try {
+      await step.run();
+    } catch (e) {
+      const message = e instanceof Error ? e.message : String(e);
+      console.error(`[seed] ${step.name} failed: ${message}`);
+    }
+  }
+}
+
+module.exports = { runSeedersSerially };

package/src/main/lib/scheduler/loopEfficiency.cjs

@@ -0,0 +1,109 @@
+/**
+ * loopEfficiency.cjs — pure calculator for the scheduler's real throughput
+ * metric: validated PRDs per unit of usage, per project.
+ *
+ * Why: the scheduler is bound by the account's usage window, not by slots, so
+ * "verified PRDs per usage %" (and $ per verified PRD) is what matters. Also
+ * makes the "wasted runs <= 5%" target in scheduler-operations.md computable.
+ *
+ * Pure: no I/O, no Date.now(), no mutation of inputs.
+ * Complexity O(R + V + P log P): one pass over runs, one over validations,
+ * then a sort of the P project rows.
+ */
+
+'use strict';
+
+const path = require('path');
+const { COMPLETED_EQUIVALENT_VERDICTS } = require('./terminalRunOutcome.cjs');
+
+/** @param {unknown} t @param {number} fromMs @param {number} toMs */
+function inWindow(t, fromMs, toMs) {
+  return typeof t === 'number' && Number.isFinite(t) && t >= fromMs && t < toMs;
+}
+
+/** @param {unknown} slug */
+function normSlug(slug) {
+  return String(slug == null ? '' : slug).replace(/^\d+-/, '');
+}
+
+/**
+ * @param {{
+ *   runs?: Array<{ cwd: string, slug: string, startedAtMs: number, costUsd?: number, verdict: string | null }>,
+ *   validations?: Array<{ cwd: string, slug: string, verdict: 'VERIFIED' | 'REFUTED', atMs: number }>,
+ *   fromMs: number,
+ *   toMs: number,
+ *   weeklyUtilizationPct?: number | null,
+ * }} input
+ */
+function computeLoopEfficiency({ runs, validations, fromMs, toMs, weeklyUtilizationPct }) {
+  /** @type {Map<string, { cwd: string, runs: number, wastedRuns: number, executorUsd: number, last: Map<string, { atMs: number, verdict: string }> }>} */
+  const byCwd = new Map();
+  const bucket = (/** @type {string} */ cwd) => {
+    let b = byCwd.get(cwd);
+    if (!b) {
+      b = { cwd, runs: 0, wastedRuns: 0, executorUsd: 0, last: new Map() };
+      byCwd.set(cwd, b);
+    }
+    return b;
+  };
+
+  for (const r of runs || []) {
+    if (!r || !inWindow(r.startedAtMs, fromMs, toMs)) continue;
+    const b = bucket(String(r.cwd));
+    b.runs += 1;
+    const v = r.verdict;
+    if (v != null && v !== 'clean' && !COMPLETED_EQUIVALENT_VERDICTS.has(v)) b.wastedRuns += 1;
+    const cost = Number(r.costUsd);
+    if (Number.isFinite(cost)) b.executorUsd += cost;
+  }
+
+  for (const v of validations || []) {
+    if (!v || !inWindow(v.atMs, fromMs, toMs)) continue;
+    const b = bucket(String(v.cwd));
+    const key = normSlug(v.slug);
+    const prev = b.last.get(key);
+    if (!prev || v.atMs >= prev.atMs) b.last.set(key, { atMs: v.atMs, verdict: v.verdict });
+  }
+
+  const rows = [];
+  const totals = { runs: 0, wastedRuns: 0, verified: 0, refuted: 0, executorUsd: 0, wastedRunRate: 0 };
+  for (const b of byCwd.values()) {
+    let verified = 0;
+    let refuted = 0;
+    for (const { verdict } of b.last.values()) {
+      if (verdict === 'VERIFIED') verified += 1;
+      else if (verdict === 'REFUTED') refuted += 1;
+    }
+    rows.push({
+      cwd: b.cwd,
+      project: path.basename(b.cwd),
+      runs: b.runs,
+      wastedRuns: b.wastedRuns,
+      verified,
+      refuted,
+      executorUsd: b.executorUsd,
+      usdPerVerified: verified > 0 ? b.executorUsd / verified : null,
+    });
+    totals.runs += b.runs;
+    totals.wastedRuns += b.wastedRuns;
+    totals.verified += verified;
+    totals.refuted += refuted;
+    totals.executorUsd += b.executorUsd;
+  }
+  totals.wastedRunRate = totals.runs > 0 ? totals.wastedRuns / totals.runs : 0;
+
+  rows.sort((a, b) => b.executorUsd - a.executorUsd || (a.project < b.project ? -1 : a.project > b.project ? 1 : 0));
+
+  const pct = typeof weeklyUtilizationPct === 'number' ? weeklyUtilizationPct : NaN;
+  const hasPct = Number.isFinite(pct) && pct > 0;
+  return {
+    fromMs,
+    toMs,
+    rows,
+    totals,
+    weeklyUtilizationPct: weeklyUtilizationPct == null ? null : weeklyUtilizationPct,
+    verifiedPerUsagePct: hasPct ? totals.verified / pct : null,
+  };
+}
+
+module.exports = { computeLoopEfficiency };