claude-code-session-manager 0.122.0 → 0.123.0

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

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

@@ -0,0 +1,138 @@
+'use strict';
+/**
+ * prdBodyPatch.cjs — pure structured patch of a PRD body. Replaces only the
+ * `# Gate`, `# Files` and/or `# Acceptance criteria` sections, validating and
+ * rendering gate/files with the same prdGateFiles.cjs functions createPrd uses.
+ * No I/O.
+ */
+
+const { validateGate, validateFiles, renderFilesSection, renderGateSection } = require('./prdGateFiles.cjs');
+const { resolveGate, parseChain, isNoneGate } = require('../scheduler/definitionOfDone.cjs');
+
+const H_AC = '# Acceptance criteria';
+const H_FILES = '# Files';
+const H_GATE = '# Gate';
+const H_NOTES = '# Implementation notes';
+const H_STANDARDS = '## Engineering standards';
+
+/** Locate a heading's span [start, end) in lines, ignoring fenced code. */
+function findSection(lines, heading) {
+  let inFence = false;
+  let start = -1;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^\s*```/.test(line)) { inFence = !inFence; continue; }
+    if (inFence) continue;
+    if (start === -1) {
+      if (line === heading) start = i;
+    } else if (/^#{1,2} /.test(line)) {
+      return { start, end: i };
+    }
+  }
+  return start === -1 ? null : { start, end: lines.length };
+}
+
+function findHeadingIndex(lines, heading) {
+  const s = findSection(lines, heading);
+  return s ? s.start : -1;
+}
+
+function replaceSection(lines, heading, rendered, insertBeforeHeadings) {
+  const span = findSection(lines, heading);
+  if (span) {
+    lines.splice(span.start, span.end - span.start, ...rendered);
+    return;
+  }
+  let at = lines.length;
+  for (const h of insertBeforeHeadings) {
+    const idx = findHeadingIndex(lines, h);
+    if (idx !== -1) { at = idx; break; }
+  }
+  lines.splice(at, 0, ...rendered);
+}
+
+function gateSignature(body) {
+  const r = resolveGate(body);
+  return JSON.stringify([r.source, r.sequence]);
+}
+
+/**
+ * @param {string} body
+ * @param {{gate?: string[], files?: string[], acceptanceCriteria?: string[]}} patch
+ * @returns {{ok:true, body:string, warnings:string[]}|{ok:false, error:string}}
+ */
+function applyStructuredPrdPatch(body, patch) {
+  if (typeof body !== 'string') return { ok: false, error: 'body must be a string.' };
+  if (!patch || typeof patch !== 'object') return { ok: false, error: 'patch must be an object.' };
+  const hasGate = patch.gate !== undefined;
+  const hasFiles = patch.files !== undefined;
+  const hasAc = patch.acceptanceCriteria !== undefined;
+  if (!hasGate && !hasFiles && !hasAc) {
+    return { ok: false, error: 'patch must name at least one of gate, files, acceptanceCriteria.' };
+  }
+
+  let warnings = [];
+  let gateCommands = null;
+  let filesList = null;
+  let acLines = null;
+
+  if (hasGate) {
+    const g = validateGate(patch.gate);
+    if (!g.ok) return { ok: false, error: g.error };
+    gateCommands = g.commands;
+    warnings = warnings.concat(g.warnings || []);
+  }
+  if (hasFiles) {
+    const f = validateFiles(patch.files);
+    if (!f.ok) return { ok: false, error: f.error };
+    filesList = f.files;
+  }
+  if (hasAc) {
+    const ac = patch.acceptanceCriteria;
+    if (!Array.isArray(ac) || ac.length === 0) {
+      return { ok: false, error: 'acceptanceCriteria must be a non-empty array of strings.' };
+    }
+    acLines = [];
+    for (let i = 0; i < ac.length; i++) {
+      if (typeof ac[i] !== 'string' || ac[i].trim() === '') {
+        return { ok: false, error: `acceptanceCriteria entry ${i + 1}: must be a non-empty string.` };
+      }
+      if (/[\r\n]/.test(ac[i])) {
+        return { ok: false, error: `acceptanceCriteria entry ${i + 1}: must not contain a newline.` };
+      }
+      acLines.push(`- [ ] ${ac[i].trim()}`);
+    }
+  }
+
+  const lines = body.split('\n');
+  if (hasAc) {
+    if (!findSection(lines, H_AC)) return { ok: false, error: `body has no "${H_AC}" section to patch.` };
+    replaceSection(lines, H_AC, [H_AC, '', ...acLines, ''], []);
+  }
+  if (hasFiles) {
+    replaceSection(lines, H_FILES, renderFilesSection(filesList), [H_NOTES, H_STANDARDS]);
+  }
+  if (hasGate) {
+    replaceSection(lines, H_GATE, renderGateSection(gateCommands), [H_STANDARDS]);
+  }
+  const next = lines.join('\n');
+
+  // Read-back with the scheduler's own reader, as createPrd does.
+  if (hasGate) {
+    const expectedSource = gateCommands.length === 1 && isNoneGate(gateCommands[0]) ? 'none' : 'explicit';
+    const expectedSequence = expectedSource === 'none' ? [] : gateCommands.flatMap(parseChain);
+    const resolved = resolveGate(next);
+    if (resolved.source !== expectedSource || JSON.stringify(resolved.sequence) !== JSON.stringify(expectedSequence)) {
+      return {
+        ok: false,
+        error: 'The PRD text holds another gate fence (three backticks + gate) outside the # Gate section, so the scheduler would read the wrong gate. Remove it and retry.',
+      };
+    }
+  } else if (gateSignature(next) !== gateSignature(body)) {
+    return { ok: false, error: 'The patch would change how the scheduler reads the PRD gate (stray gate fence in the new text).' };
+  }
+
+  return { ok: true, body: next, warnings };
+}
+
+module.exports = { applyStructuredPrdPatch };

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

@@ -32,7 +32,9 @@ 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 { splitFrontmatter } = require('./prdFrontmatter.cjs');
 const { sizingWarnings } = require('./prdSizing.cjs');
+const telemetryCounters = require('../telemetry/telemetryCounters.cjs');
 const { execGit } = require('../git/gitExec.cjs');
 const { extractRepoPathCandidates, worktreeReachWarnings } = require('./prdWorktreeReach.cjs');
 const { validateGate, validateFiles, renderFilesSection, renderGateSection } = require('./prdGateFiles.cjs');
@@ -224,7 +226,21 @@ async function worktreeReachAdvisory(input, cwd) {
  * on failure — `status` is the HTTP status code the caller should map errors to
  * (400/409/500), left to the caller since only the HTTP route needs it.
  */
+const inFlightCreates = new Set();
+
 async function createPrd(input, remote) {
+  const ctl = { key: null };
+  try {
+    return await createPrdInner(input, remote, ctl);
+  } finally {
+    if (ctl.key) inFlightCreates.delete(ctl.key);
+  }
+}
+
+async function createPrdInner(input, remote, ctl, opts = {}) {
+  // opts.dryRun: run every check, allocate/write nothing, return the prepared
+  // entry (createPrdBatch's validate phase). opts.extraDepSlugs: bare slugs of
+  // sibling batch entries, accepted as dependsOn targets.
   // cwd is untrusted AND, since this PRD, optional — a caller inside an
   // Epic's git worktree naturally passes its worktree pwd (or omits cwd
   // entirely and relies on originClaudeSessionId/sourcePromptId). Resolve the
@@ -249,7 +265,7 @@ async function createPrd(input, remote) {
 
   if (!resolved.cwd) {
     return {
-      ok: false,
+      ok: false, applied: false,
       status: 400,
       error: 'cwd is required — pass cwd explicitly, or originClaudeSessionId/sourcePromptId that resolves '
         + 'to an existing, already-approved Epic (create/approve an Epic first)',
@@ -264,7 +280,7 @@ async function createPrd(input, remote) {
   try {
     realCwd = config.validatePath(cwd);
   } catch (e) {
-    return { ok: false, status: 400, error: `cwd rejected: ${e?.message ?? 'outside allowed roots'}` };
+    return { ok: false, applied: false, status: 400, error: `cwd rejected: ${e?.message ?? 'outside allowed roots'}` };
   }
   // Register this project's cwd as a write-allowed root (config.cjs's
   // validateWrite gate). Chat-only Epics (headless claude -p, no Terminal
@@ -313,7 +329,7 @@ async function createPrd(input, remote) {
         const nonInteractive = Boolean(process.env.SM_SCHEDULER_JOB_SLUG);
         if (!nonInteractive) {
           return {
-            ok: false,
+            ok: false, applied: false,
             status: 400,
             error: `Epic ${input.sourcePromptId} already has incomplete PRDs — pass disposition: "append" ` +
               '(extend the existing chain behind its current tail) or "new-head" (an independent root, ' +
@@ -340,7 +356,7 @@ async function createPrd(input, remote) {
     const nnMatch = SLUG_HAS_NN_PREFIX_RE.exec(input.slug);
     if (nnMatch) {
       return {
-        ok: false,
+        ok: false, applied: false,
         status: 400,
         error: `slug "${input.slug}" already starts with a numeric prefix "${nnMatch[1]}-" — the allocator ` +
           `owns the NN- prefix, not the caller. Pass the bare name instead (e.g. "${input.slug.slice(nnMatch[0].length)}").`,
@@ -350,7 +366,7 @@ async function createPrd(input, remote) {
 
   const slug = input.slug || deriveSlugFromTitle(input.title);
   if (!slug || !PRD_CREATE_SLUG_RE.test(slug)) {
-    return { ok: false, status: 400, error: 'could not derive a valid kebab-case slug from title; supply "slug" explicitly' };
+    return { ok: false, applied: false, status: 400, error: 'could not derive a valid kebab-case slug from title; supply "slug" explicitly' };
   }
 
   // NN allocation is delegated to allocateParallelGroup() (PRD 548) via the
@@ -365,21 +381,21 @@ async function createPrd(input, remote) {
   // checked BEFORE the NN allocation so a refusal burns no number.
   const hasArtifactPaths = Array.isArray(input.artifactPaths) && input.artifactPaths.length > 0;
   if (input.deliverable != null && input.deliverable !== 'artifact') {
-    return { ok: false, status: 400, error: 'deliverable must be exactly "artifact" when given' };
+    return { ok: false, applied: false, status: 400, error: 'deliverable must be exactly "artifact" when given' };
   }
   if (input.deliverable === 'artifact' && !hasArtifactPaths) {
-    return { ok: false, status: 400, error: 'deliverable: "artifact" requires a non-empty artifactPaths — name every git-excluded file this PRD produces' };
+    return { ok: false, applied: false, status: 400, error: 'deliverable: "artifact" requires a non-empty artifactPaths — name every git-excluded file this PRD produces' };
   }
   if (input.artifactPaths != null && input.deliverable !== 'artifact') {
-    return { ok: false, status: 400, error: 'artifactPaths requires deliverable: "artifact" — artifactPaths given without it' };
+    return { ok: false, applied: false, status: 400, error: 'artifactPaths requires deliverable: "artifact" — artifactPaths given without it' };
   }
   if (hasArtifactPaths) {
     for (const ap of input.artifactPaths) {
       if (typeof ap !== 'string' || !ap.trim() || /[\r\n,\[\]]/.test(ap)) {
-        return { ok: false, status: 400, error: `artifactPaths entry ${JSON.stringify(ap)} must be a non-empty single-line path without commas or brackets` };
+        return { ok: false, applied: false, status: 400, error: `artifactPaths entry ${JSON.stringify(ap)} must be a non-empty single-line path without commas or brackets` };
       }
       if (ap.includes('..')) {
-        return { ok: false, status: 400, error: `artifactPaths entry "${ap}" must not contain ".."` };
+        return { ok: false, applied: false, status: 400, error: `artifactPaths entry "${ap}" must not contain ".."` };
       }
     }
   }
@@ -403,18 +419,18 @@ async function createPrd(input, remote) {
   }
   for (const [fieldLabel, text] of [['goal', input.goal], ['implementation notes', input.implementationNotes]]) {
     const headingError = headingGuardError(fieldLabel, text);
-    if (headingError) return { ok: false, status: 400, error: headingError };
+    if (headingError) return { ok: false, applied: false, status: 400, error: headingError };
   }
   if (Array.isArray(input.acceptanceCriteria)) {
     for (const entry of input.acceptanceCriteria) {
       const headingError = headingGuardError('acceptance criteria', entry);
-      if (headingError) return { ok: false, status: 400, error: headingError };
+      if (headingError) return { ok: false, applied: false, status: 400, error: headingError };
     }
   }
   if (Array.isArray(input.outOfScope)) {
     for (const entry of input.outOfScope) {
       const headingError = headingGuardError('out of scope', entry);
-      if (headingError) return { ok: false, status: 400, error: headingError };
+      if (headingError) return { ok: false, applied: false, status: 400, error: headingError };
     }
   }
 
@@ -427,7 +443,7 @@ async function createPrd(input, remote) {
   if (input.gate !== undefined) {
     const gateValidation = validateGate(input.gate);
     if (!gateValidation.ok) {
-      return { ok: false, status: 400, error: gateValidation.error };
+      return { ok: false, applied: false, status: 400, error: gateValidation.error };
     }
     gateCommands = gateValidation.commands;
     extraWarnings.push(...gateValidation.warnings);
@@ -438,7 +454,7 @@ async function createPrd(input, remote) {
   if (input.files !== undefined) {
     const filesValidation = validateFiles(input.files);
     if (!filesValidation.ok) {
-      return { ok: false, status: 400, error: filesValidation.error };
+      return { ok: false, applied: false, status: 400, error: filesValidation.error };
     }
     filesList = filesValidation.files;
   } else {
@@ -450,6 +466,18 @@ async function createPrd(input, remote) {
   // 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}`)) {
+    const inFlightKey = `${input.sourcePromptId}\u0000${slug}`;
+    if (!opts.dryRun && inFlightCreates.has(inFlightKey)) {
+      return {
+        ok: false, applied: false,
+        status: 409,
+        error: `A create for slug "${slug}" in this Epic is still in progress — wait for it to finish, then retry the same call`,
+      };
+    }
+    if (!opts.dryRun) {
+      inFlightCreates.add(inFlightKey);
+      ctl.key = inFlightKey;
+    }
     let epicDirs = [];
     try {
       const prdsDir = resolveEpicPrdWriteDir(cwd, input.sourcePromptId);
@@ -460,8 +488,31 @@ async function createPrd(input, remote) {
       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) {
+        let existingTitle = null;
+        try {
+          existingTitle = splitFrontmatter(await fsp.readFile(path.join(dir, dup), 'utf8')).fm.title ?? null;
+        } catch { /* unreadable — treat as different */ }
+        if (existingTitle !== null && String(existingTitle).trim() === String(input.title ?? '').trim()) {
+          const existingSlug = dup.slice(0, -3);
+          let enqueuedExisting = false;
+          try {
+            if (typeof remote.getJob === 'function') enqueuedExisting = Boolean(await remote.getJob(existingSlug));
+          } catch { /* non-fatal */ }
+          return {
+            ok: true,
+            applied: true,
+            alreadyExisted: true,
+            nn: Number((/^(\d+)-/.exec(dup) || [])[1]),
+            filename: dup,
+            prdPath: path.join(dir, dup),
+            epicId: input.sourcePromptId,
+            enqueued: enqueuedExisting,
+            note: 'PRD was not written again: this Epic already has that file with the same title, which usually means an earlier call\'s response was lost, so treat it as created.',
+            warnings: [],
+          };
+        }
         return {
-          ok: false,
+          ok: false, applied: 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.',
@@ -470,7 +521,8 @@ async function createPrd(input, remote) {
     }
   }
 
-  const nn = await remote.allocateParallelGroup(input.cwd);
+  // Dry run burns no number: a placeholder keeps the filename-shaped guards below meaningful.
+  const nn = opts.dryRun ? 9999999 : await remote.allocateParallelGroup(input.cwd);
   const filenameSlug = `${nn}-${slug}`;
 
   // Fix-chain depth guard (PRD 1113): refuse a fix-of-a-fix before it's ever
@@ -482,7 +534,7 @@ async function createPrd(input, remote) {
   if (chainDepth > FIX_CHAIN_DEPTH_CAP) {
     const base = baseSlugOf(filenameSlug);
     return {
-      ok: false,
+      ok: false, applied: false,
       status: 409,
       error: `Fix-chain depth cap exceeded: "${base}" has already failed to close ${chainDepth} time(s) for ` +
         `infrastructure reasons (refusing to write "${filenameSlug}.md" at depth ${chainDepth}). Authoring a ` +
@@ -505,7 +557,7 @@ async function createPrd(input, remote) {
   // — but only when spawnInvestigation authors it, never through this API).
   if (isFixPlanSlug(filenameSlug)) {
     return {
-      ok: false,
+      ok: false, applied: false,
       status: 400,
       error: `slug "${filenameSlug}" collides with the reserved NN-fix-... fix-plan naming convention ` +
         '(reserved for PRDs the scheduler\'s own investigation loop authors itself). Reword the title/slug ' +
@@ -519,9 +571,9 @@ async function createPrd(input, remote) {
   // no existence guard (by design, it doubles as the edit-in-place
   // path for Scheduler UI PRD edits), so "create" must not silently
   // clobber an existing job's PRD.
-  const existing = await remote.readPrd(filenameSlug, input.cwd);
+  const existing = opts.dryRun ? null : await remote.readPrd(filenameSlug, input.cwd);
   if (existing?.ok) {
-    return { ok: false, status: 409, error: `PRD already exists: ${filenameSlug}.md` };
+    return { ok: false, applied: false, status: 409, error: `PRD already exists: ${filenameSlug}.md` };
   }
 
   // Write-time FK check (throw on write, report on read — see
@@ -534,7 +586,7 @@ async function createPrd(input, remote) {
     try {
       await assertAgentTypeWritable(input.cwd, input.agentType);
     } catch (e) {
-      return { ok: false, status: 400, error: e?.message ?? 'invalid agentType' };
+      return { ok: false, applied: false, status: 400, error: e?.message ?? 'invalid agentType' };
     }
   }
 
@@ -558,13 +610,13 @@ async function createPrd(input, remote) {
     }
     if (listing) {
       depRows = listing.prds ?? [];
-      const candidateSlugs = depRows.map((p) => p.slug);
+      const candidateSlugs = [...depRows.map((p) => p.slug), ...(opts.extraDepSlugs ?? [])];
       for (const dep of input.dependsOn) {
         if (resolveDepSlug(dep, candidateSlugs).length > 0) continue;
         const near = findNearMatches(dep, candidateSlugs);
         const suggestion = near.length ? ` Closest existing slug(s): ${near.join(', ')}.` : '';
         return {
-          ok: false,
+          ok: false, applied: false,
           status: 400,
           error: `dependsOn entry "${dep}" does not resolve to any existing PRD in this project.${suggestion} ` +
             'Pass the bare name (preferred) or the exact NN-prefixed slug of an existing PRD.',
@@ -584,6 +636,7 @@ async function createPrd(input, remote) {
       console.warn(`[prdCreate] dependsOn spans plans ${inherited.diverged.join(', ')} — inheriting ${planId} (lowest-numbered dependency)`);
     }
   }
+  const inheritedPlanId = planId;
   if (!planId) planId = mintPlanId();
 
   const body = buildPrdBody({ ...input, planId, gate: gateCommands, files: filesList });
@@ -603,7 +656,7 @@ async function createPrd(input, remote) {
       && JSON.stringify(resolved.sequence) === JSON.stringify(expectedSequence);
     if (!matches) {
       return {
-        ok: false,
+        ok: false, applied: false,
         status: 400,
         error: 'The PRD text already holds a gate fence (three backticks + gate), so the scheduler would read '
           + 'the wrong gate. Remove it from the goal, implementation notes, acceptance criteria, out of scope '
@@ -612,9 +665,16 @@ async function createPrd(input, remote) {
     }
   }
 
+  if (opts.dryRun) {
+    return {
+      ok: true, dryRun: true, slug, input, gateCommands, filesList,
+      inheritedPlanId, warnings: [...extraWarnings, ...sizingWarnings(input)],
+    };
+  }
+
   const writeResult = await remote.writePrd(filenameSlug, body, input.cwd);
   if (!writeResult?.ok) {
-    return { ok: false, status: 500, error: writeResult?.error ?? 'write failed' };
+    return { ok: false, applied: false, status: 500, error: writeResult?.error ?? 'write failed' };
   }
 
   // Trace-back point for "who/what created this PRD" (auditLog.cjs) — every
@@ -627,6 +687,8 @@ async function createPrd(input, remote) {
     sourcePromptId: input.sourcePromptId ?? null,
     sourceTabId: input.sourceTabId ?? null,
   });
+  // Anonymous counter: enum-mapped agentType only (telemetryCounters.cjs).
+  telemetryCounters.trackPrdCreate({ agentType: input.agentType || DEFAULT_PRD_AGENT_TYPE });
 
   // PRD 1446: writePrd() succeeding used to just promise "the next scheduler
   // reconcile pass (~1 minute)" adopts this file — but nothing reliably ran
@@ -642,7 +704,12 @@ async function createPrd(input, remote) {
   let enqueued = false;
   if (typeof remote.requestReconcile === 'function') {
     try {
-      await remote.requestReconcile();
+      let timer;
+      const reconcile = Promise.resolve().then(() => remote.requestReconcile());
+      // Late rejection (after the race is lost) must never be unhandled.
+      reconcile.catch((e) => console.warn(`[prdCreate] requestReconcile failed for ${filenameSlug} (non-fatal): ${e?.message ?? e}`));
+      const bound = new Promise((resolve) => { timer = setTimeout(resolve, 2000); });
+      try { await Promise.race([reconcile, bound]); } finally { clearTimeout(timer); }
       if (typeof remote.getJob === 'function') {
         enqueued = Boolean(await remote.getJob(filenameSlug));
       }
@@ -662,6 +729,7 @@ async function createPrd(input, remote) {
   // row before this function returned — it is not a fabricated status.
   return {
     ok: true,
+    applied: true,
     nn,
     filename: `${filenameSlug}.md`,
     prdPath: writeResult.path ?? null,
@@ -684,6 +752,128 @@ async function createPrd(input, remote) {
   };
 }
 
+const PRD_BATCH_MAX = 40;
+
+/**
+ * Create several PRDs all-or-nothing. Every entry goes through createPrd's own
+ * validation (dry run: no NN, no file); `dependsOn` may also name other entries
+ * of the batch by bare slug, earlier or later. Only when every entry validates
+ * and the intra-batch graph is acyclic are NNs allocated and files written; a
+ * write failure unlinks what this call already wrote. Allocated NNs are never
+ * reissued (the allocator's high-water only moves up), so a rollback leaves a
+ * gap, not an inconsistency.
+ */
+async function createPrdBatch(inputs, remote, opts = {}) {
+  const fail = (errors) => ({ ok: false, applied: false, errors });
+  if (!Array.isArray(inputs) || inputs.length === 0) return fail([{ index: -1, slug: null, error: 'batch needs at least one entry' }]);
+  if (inputs.length > PRD_BATCH_MAX) return fail([{ index: -1, slug: null, error: `batch has ${inputs.length} entries; the maximum is ${PRD_BATCH_MAX}` }]);
+
+  const envelope = {};
+  for (const k of ['cwd', 'originClaudeSessionId', 'originProjectRoot', 'sourcePromptId']) {
+    if (opts[k] != null) envelope[k] = opts[k];
+  }
+  const entries = inputs.map((e) => ({ ...envelope, ...e }));
+
+  // Pass 1: slugs (cheap, so duplicates / cycles are reported before any I/O).
+  const slugs = entries.map((e) => e.slug || deriveSlugFromTitle(e.title));
+  const errors = [];
+  const firstIndex = new Map();
+  slugs.forEach((s, i) => {
+    if (!s) return;
+    if (firstIndex.has(s)) errors.push({ index: i, slug: s, error: `duplicate slug "${s}" in batch (also entry ${firstIndex.get(s)})` });
+    else firstIndex.set(s, i);
+  });
+  if (errors.length) return fail(errors);
+  const batchSlugs = slugs.filter(Boolean);
+
+  // Pass 2: per-entry validation through createPrd's own checks.
+  const prepared = [];
+  for (let i = 0; i < entries.length; i++) {
+    const r = await createPrdInner(entries[i], remote, { key: null }, { dryRun: true, extraDepSlugs: batchSlugs });
+    if (!r.ok) { errors.push({ index: i, slug: slugs[i] ?? null, error: r.error }); continue; }
+    if (r.alreadyExisted) { errors.push({ index: i, slug: slugs[i], error: `slug "${slugs[i]}" already exists in this Epic as "${r.filename}"` }); continue; }
+    prepared.push(r);
+  }
+  if (errors.length) return fail(errors);
+  const sameTarget = prepared.every((p) => p.input.cwd === prepared[0].input.cwd && (p.input.sourcePromptId ?? null) === (prepared[0].input.sourcePromptId ?? null));
+  if (!sameTarget) return fail([{ index: -1, slug: null, error: 'all batch entries must resolve to the same project and Epic' }]);
+
+  // Cycle detection: DFS over intra-batch dependsOn edges (bare-slug match).
+  const edges = prepared.map((p) => (p.input.dependsOn ?? []).filter((d) => firstIndex.has(d)).map((d) => firstIndex.get(d)));
+  const state = new Array(prepared.length).fill(0);
+  let cycle = null;
+  const visit = (n, trail) => {
+    if (cycle) return;
+    state[n] = 1;
+    for (const m of edges[n]) {
+      if (state[m] === 1) { cycle = [...trail.slice(trail.indexOf(m)), n, m].map((x) => slugs[x]); return; }
+      if (state[m] === 0) visit(m, [...trail, n]);
+      if (cycle) return;
+    }
+    state[n] = 2;
+  };
+  for (let i = 0; i < prepared.length && !cycle; i++) if (state[i] === 0) visit(i, []);
+  if (cycle) {
+    const at = firstIndex.get(cycle[0]);
+    return fail([{ index: at, slug: cycle[0], error: `dependsOn cycle inside batch: ${cycle.join(' -> ')}` }]);
+  }
+
+  // One planId for the whole batch unless an entry inherits one from existing deps.
+  const planId = prepared.map((p) => p.inheritedPlanId).find(Boolean) || mintPlanId();
+
+  // Write phase: allocate + write in input order; unlink on any failure.
+  const written = [];
+  const results = [];
+  const rollback = async () => {
+    for (const w of written) {
+      try {
+        if (w.path) await fsp.unlink(w.path);
+        else if (typeof remote.deletePrd === 'function') await remote.deletePrd(w.filenameSlug, w.cwd);
+      } catch (e) { console.warn(`[prdCreate] batch rollback could not remove ${w.filenameSlug}: ${e?.message ?? e}`); }
+    }
+  };
+  for (let i = 0; i < prepared.length; i++) {
+    const p = prepared[i];
+    let nn; let filenameSlug;
+    try {
+      nn = await remote.allocateParallelGroup(p.input.cwd);
+      filenameSlug = `${nn}-${p.slug}`;
+      const body = buildPrdBody({ ...p.input, planId, gate: p.gateCommands, files: p.filesList });
+      const w = await remote.writePrd(filenameSlug, body, p.input.cwd);
+      if (!w?.ok) throw new Error(w?.error ?? 'write failed');
+      written.push({ filenameSlug, path: w.path ?? null, cwd: p.input.cwd });
+      results.push({ slug: p.slug, nn, filename: `${filenameSlug}.md`, warnings: p.warnings });
+    } catch (e) {
+      await rollback();
+      return fail([{ index: i, slug: p.slug, error: `write failed (batch rolled back): ${e?.message ?? e}` }]);
+    }
+  }
+
+  for (let i = 0; i < prepared.length; i++) {
+    const p = prepared[i];
+    appendAuditEvent('prd_create', {
+      cwd: p.input.cwd, slug: `${results[i].nn}-${p.slug}`, title: p.input.title,
+      sourcePromptId: p.input.sourcePromptId ?? null, sourceTabId: p.input.sourceTabId ?? null, batch: true,
+    });
+    telemetryCounters.trackPrdCreate({ agentType: p.input.agentType || DEFAULT_PRD_AGENT_TYPE });
+  }
+
+  // One bounded reconcile after the last write (best-effort, as in createPrd).
+  if (typeof remote.requestReconcile === 'function') {
+    let timer;
+    try {
+      const reconcile = Promise.resolve().then(() => remote.requestReconcile());
+      reconcile.catch((e) => console.warn(`[prdCreate] batch requestReconcile failed (non-fatal): ${e?.message ?? e}`));
+      const bound = new Promise((resolve) => { timer = setTimeout(resolve, 2000); });
+      await Promise.race([reconcile, bound]);
+    } catch (e) {
+      console.warn(`[prdCreate] batch requestReconcile failed (non-fatal): ${e?.message ?? e}`);
+    } finally { clearTimeout(timer); }
+  }
+
+  return { ok: true, applied: true, prds: results };
+}
+
 /**
  * Registers the create-prd admin HTTP route (PRD 689 — moved verbatim out of
  * the former standalone admin HTTP server module's handleRequest, no behavior
@@ -720,6 +910,7 @@ function registerAdminRoute(adminHttp, remote) {
     // Mirror createPrd()'s own honest shape verbatim — never re-add a
     // 'status' field here. See createPrd's return above for why.
     sendJson(res, 200, {
+      ...(result.alreadyExisted ? { alreadyExisted: true } : {}),
       nn: result.nn,
       filename: result.filename,
       prdPath: result.prdPath ?? null,
@@ -731,6 +922,31 @@ function registerAdminRoute(adminHttp, remote) {
       warnings: result.warnings,
     });
   });
+
+  adminHttp.registerRoute('POST', '/admin/scheduler/create-prds', async (req, res) => {
+    const raw = await readBody(req);
+    let parsed;
+    try {
+      parsed = raw ? JSON.parse(raw) : {};
+    } catch {
+      sendJson(res, 400, { ok: false, applied: false, error: 'invalid JSON body' });
+      return;
+    }
+    let input;
+    try {
+      input = schemas.adminCreatePrds.parse(parsed);
+    } catch (e) {
+      sendJson(res, 400, { ok: false, applied: false, error: 'invalid PRD batch payload', details: e?.issues ?? e?.message });
+      return;
+    }
+    const { prds, ...envelope } = input;
+    const result = await createPrdBatch(prds, remote, envelope);
+    if (!result.ok) {
+      sendJson(res, 400, { ok: false, applied: false, errors: result.errors });
+      return;
+    }
+    sendJson(res, 200, { ok: true, applied: true, prds: result.prds });
+  });
 }
 
 module.exports = {
@@ -741,5 +957,7 @@ module.exports = {
   buildPrdBody,
   resolveSourcePromptIdFromClaudeSession,
   createPrd,
+  createPrdBatch,
+  PRD_BATCH_MAX,
   registerAdminRoute,
 };