claude-code-session-manager 0.57.0 → 0.58.0

package/src/main/lib/{rcaFeedbackHook.cjs → rcaReport.cjs}

@@ -1,13 +1,21 @@
 'use strict';
 
 /**
- * rcaFeedbackHook.cjs — files a deterministic Root Cause Analysis feedback
- * item when a scheduler job is parked in `needs_review`.
+ * rcaReport.cjs — writes a deterministic Root Cause Analysis report into the
+ * run directory when a scheduler job is parked in `needs_review`.
  *
  * Mirrors the dodDrainHook.cjs pattern: fire-and-forget, idempotent,
  * kill-switched, never throws to the caller. Unlike the DoD gate this fires
  * per-job at the needs_review transition, not at queue drain.
  *
+ * This module creates NOTHING but a markdown file next to the run's own log.
+ * It used to file a `proposed` Epic per parked job; Epics are now created in
+ * exactly one place — the human pressing New Epic (see epicMint.cjs's
+ * SINGLE-CREATOR LAW). Surfacing the parked job back to a human is the
+ * scheduler's job (notifyNeedsReview → appendResponseEventIfKnown), which
+ * routes it into the Epic that AUTHORED the PRD rather than opening a
+ * sibling Epic about it.
+ *
  * No LLM calls live here — the RCA body is assembled deterministically from
  * the run's meta.json, log tail, and the original PRD's acceptance-criteria
  * section. When an Opus auto-fix investigation later runs (spawnInvestigation
@@ -17,34 +25,17 @@
  *
  * Kill-switch: SM_RCA_DISABLE=1 (mirrors SM_DOD_DISABLE / SM_SUPERVISOR_DISABLE).
  *
- * Electron-free by design (no require('electron')) so tests stay hermetic.
- * config.cjs itself requires('electron'), but that resolves to a harmless
- * string (not the electron module) when required outside the Electron
- * runtime, and this lib never touches ipcMain — only the atomic-write /
- * path-validation helpers.
+ * Electron-free by design (no require('electron')) so tests stay hermetic —
+ * it only reads run artifacts and writes one markdown file into the run dir
+ * the caller already owns.
  */
 
 const fs = require('node:fs');
-const os = require('node:os');
 const path = require('node:path');
-const config = require('../config.cjs');
-const { ensureEpic, findJoinableEpic } = require('./epicMint.cjs');
 const { splitFrontmatter } = require('./prdFrontmatter.cjs');
 const { readTail } = require('./fileTail.cjs');
 const { resolvePrdWriteDir } = require('./prdLocations.cjs');
 
-// The one project this hook always knows how to reach, used as the fallback
-// destination when a job's own cwd has no feedback inbox.
-const SM_REPO_ROOT = path.join(os.homedir(), 'Projects', 'session-manager');
-
-// NEVER write here: ~/.claude/session-manager/feedback/ is the scheduler's
-// auto-PRD intake (src/main/scheduler.cjs's periodic feedback sweep) — it
-// converts anything dropped there into a scheduled PRD automatically. Filing
-// an RCA there would create an RCA → auto-PRD → run → needs_review → RCA
-// cycle with no human in the loop. Both real destinations below are project
-// feedback INBOXES (consumed by /process-feedback), which is a different,
-// human/agent-triaged path.
-
 // ─── VERDICT_LABELS — deliberate duplicate ──────────────────────────────────
 // Mirrors src/renderer/components/tabs/scheduler/sched-primitives.tsx:123-131.
 // The main process cannot import renderer TSX, so this vocabulary is kept in
@@ -197,41 +188,12 @@ function extractAcceptanceCriteria(prdBody) {
   return text || null;
 }
 
-// ─── Destination resolution ──────────────────────────────────────────────────
-
-/**
- * Resolve which PROJECT the proposal is filed into.
- *   1. the job's own cwd — Epics live in every project, so this is almost
- *      always the answer.
- *   2. else session-manager's own repo, naming the target project in the body.
- *
- * The old version probed for a `session-manager-operations/feedback/`
- * directory and fell back when it was missing; with proposals there is
- * nothing to probe for — the Epic store is created on demand.
- */
-function resolveDestination(job) {
-  const jobCwd = job?.cwd;
-  if (jobCwd) {
-    return { cwd: jobCwd, allowlistRoot: jobCwd, targetProjectNote: null };
-  }
-  return {
-    cwd: SM_REPO_ROOT,
-    allowlistRoot: SM_REPO_ROOT,
-    targetProjectNote: "Filed into session-manager's own project (job had no cwd on record).",
-  };
-}
-
-/** One-line title for the proposal — goalText is what the Epics list shows,
- *  so it must stay short; the full RCA markdown rides in openingPrompt. */
-function rcaProposalTitle(job, verdict) {
+/** One-line summary of the parked job — used as the report's title and as the
+ *  text the scheduler surfaces back into the Epic that authored the PRD. */
+function rcaSummaryLine(job, verdict) {
   return `PRD ${job?.slug ?? 'unknown'} needs review: ${humanVerdict(verdict)}`;
 }
 
-function shortRunId(runId) {
-  const cleaned = String(runId ?? '').replace(/[^a-zA-Z0-9]/g, '');
-  return cleaned.slice(0, 12) || 'norun';
-}
-
 function lastNLines(text, n) {
   const lines = (text || '').split('\n');
   return lines.slice(-n).join('\n');
@@ -261,7 +223,7 @@ function readPrdBody(cwd, slug) {
  * Assemble the deterministic RCA markdown body (frontmatter + sections).
  * Pure — no I/O, no LLM.
  */
-function buildRcaMarkdown({ job, verdict, meta, logTail, acText, failureClass, investigationText, targetProjectNote }) {
+function buildRcaMarkdown({ job, verdict, meta, logTail, acText, failureClass, investigationText }) {
   const title = `Root cause: ${job.slug} → needs_review (${humanVerdict(verdict)})`;
   const fm = ['---', `title: ${title}`, 'source: scheduler-rca', 'type: rca', 'severity: normal', `prdSlug: ${job.slug}`, `runId: ${job.runId}`, `verdict: ${verdict}`, '---'].join('\n');
 
@@ -277,21 +239,21 @@ function buildRcaMarkdown({ job, verdict, meta, logTail, acText, failureClass, i
     `# The PRD's acceptance criteria\n\n${acText || '(acceptance criteria not found — original PRD may have been archived or removed)'}`,
     `# Likely failure class\n\n**${failureClass}**\n\nPrevention: ${prevention}`,
   ];
-  if (targetProjectNote) sections.push(`# Note\n\n${targetProjectNote}`);
   if (investigationText) sections.push(`## Investigation analysis\n\n${investigationText.trim()}`);
 
   return `${fm}\n\n${sections.join('\n\n')}\n`;
 }
 
 /**
- * File (or update) a deterministic RCA feedback item for a needs_review job.
+ * Write (or refresh) the deterministic RCA report for a needs_review job,
+ * as `<runDir>/root-cause-<slug>.md` — next to the run's own log, the same
+ * place the definition-of-done gate writes its report (dodDrainHook.cjs).
  * Never throws — logs one line on success/skip/error and always resolves.
  *
- * Idempotency: the destination filename is deterministic per (slug, runId).
- * A second call for the same (slug, runId) with no investigationText is a
- * no-op; a second call WITH investigationText overwrites the same file to
- * add/replace the "Investigation analysis" section rather than filing a
- * duplicate. A different runId (new run of the same slug) files a new RCA.
+ * Idempotency: one report per run directory per slug, and a run dir is
+ * per-(runId). A second call for the same run overwrites it in place, which
+ * is exactly what the investigation-enrichment pass wants (it re-renders the
+ * same body plus an "Investigation analysis" section) — never a duplicate.
  *
  * @param {object} opts
  * @param {{slug: string, cwd?: string, runId: string, exitCode?: number, error?: string, epicId?: string}} opts.job
@@ -300,10 +262,9 @@ function buildRcaMarkdown({ job, verdict, meta, logTail, acText, failureClass, i
  * @param {Array}  [opts.annotations]  Non-blocking verifier annotations (currently unused
  *                                     in the body beyond being accepted for future use).
  * @param {string} [opts.investigationText]  <RCA> block text from an Opus investigation.
- * @param {Date}   [opts.now]      Override for the date segment of the filename (testing).
- * @returns {Promise<{filed: boolean, path?: string, updated?: boolean, reason?: string}>}
+ * @returns {Promise<{filed: boolean, path?: string, summary?: string, failureClass?: string, reason?: string}>}
  */
-async function fileRcaFeedback({ job, runDir, verdict, annotations, investigationText, now } = {}) {
+async function writeRcaReport({ job, runDir, verdict, annotations, investigationText } = {}) {
   try {
     if (process.env.SM_RCA_DISABLE === '1') {
       console.log('[rca] skip: SM_RCA_DISABLE=1');
@@ -327,7 +288,10 @@ async function fileRcaFeedback({ job, runDir, verdict, annotations, investigatio
       return { filed: false, reason: 'no-verdict' };
     }
 
-    const dest = resolveDestination(job);
+    if (!runDir) {
+      console.log(`[rca] skip: no run directory for ${job.slug}`);
+      return { filed: false, reason: 'no-run-dir' };
+    }
 
     const meta = readRunMeta(runDir, job.slug);
     const logPath = runDir ? path.join(runDir, `${job.slug}.log`) : null;
@@ -336,67 +300,36 @@ async function fileRcaFeedback({ job, runDir, verdict, annotations, investigatio
     const failureClass = classifyFailure({ verdict, logTail });
 
     const markdown = buildRcaMarkdown({
-      job, verdict, meta, logTail, acText, failureClass, investigationText,
-      targetProjectNote: dest.targetProjectNote, annotations,
-    });
-
-    // File it as a PROPOSED Epic rather than a markdown file in a feedback
-    // inbox. The proposal lands directly in the Epics workspace behind an
-    // Approve & start gate: nothing runs and nothing is spent until a human
-    // approves it. This replaced the feedback-folder intake (and the
-    // process-feedback triage pass that existed only to read it back out) —
-    // the proposal IS the work item, already carrying its own session and
-    // PRD directory. reuseByGoal makes a re-trigger for the same failure
-    // join the existing proposal instead of duplicating it, which is what
-    // the old live/processed existence checks were for.
-    config.addAllowedRoot(dest.allowlistRoot);
-    const title = rcaProposalTitle(job, verdict);
-
-    // job.epicId (present on jobs authored after Epic-gating landed; absent
-    // on legacy PRDs) is the known origin Epic this failing job belonged to.
-    // Passing it straight through as ensureEpic's `epicId` would hit its
-    // explicitEpicId join-only branch, which joins unconditionally — even a
-    // 'completed' Epic. findJoinableEpic's preferEpicId strategy is the one
-    // that only joins when the Epic is still open ('proposed'/'active'), so
-    // resolve it here and only forward it when that strategy actually fires
-    // — otherwise fall through to the existing reuseByGoal/mint behavior.
-    // Once forwarded, ensureEpic joins it unconditionally by id (no second
-    // status check) — the status gate lives entirely in this resolve step.
-    let preferredEpicId;
-    if (typeof job.epicId === 'string' && job.epicId) {
-      const joinable = findJoinableEpic(dest.cwd, { goalText: title, preferEpicId: job.epicId, status: 'proposed' });
-      if (joinable && joinable.matchedBy === 'preferEpicId') {
-        preferredEpicId = joinable.epicId;
-      }
-    }
-
-    const { epicId, created } = await ensureEpic(dest.cwd, {
-      goalText: title,
-      tag: 'bug',
-      status: 'proposed',
-      reuseByGoal: true,
-      openingPrompt: markdown,
-      epicId: preferredEpicId,
-      source: { producer: 'rca-hook', prdSlug: job.slug, runId: job.runId },
+      job, verdict, meta, logTail, acText, failureClass, investigationText, annotations,
     });
 
-    console.log(`[rca] ${created ? 'proposed' : 'joined'} epic ${epicId} for ${job.slug}`);
-    return { filed: true, epicId, created, updated: !created };
+    // Raw fs (not config.cjs's writeTextAtomic) for the same reason the rest
+    // of this lib uses it: the run directory lives under
+    // ~/.claude/session-manager/scheduled-plans/runs/, which is Session-Manager
+    // runtime state, not an OWNERS namespace under a project's operations root.
+    const reportPath = path.join(runDir, `root-cause-${job.slug}.md`);
+    fs.mkdirSync(runDir, { recursive: true });
+    const tmp = `${reportPath}.tmp-${process.pid}`;
+    fs.writeFileSync(tmp, markdown);
+    fs.renameSync(tmp, reportPath);
+
+    const summary = rcaSummaryLine(job, verdict);
+    console.log(`[rca] wrote ${reportPath} (${failureClass})`);
+    return { filed: true, path: reportPath, summary, failureClass };
   } catch (e) {
-    console.error('[rca] error filing RCA feedback', e?.message ?? String(e));
+    console.error('[rca] error writing RCA report', e?.message ?? String(e));
     return { filed: false, reason: 'error', error: e?.message ?? String(e) };
   }
 }
 
 module.exports = {
-  fileRcaFeedback,
-  rcaProposalTitle,
+  writeRcaReport,
+  rcaSummaryLine,
   // Pure helpers, exported for unit tests.
   humanVerdict,
   classifyFailure,
   extractAcceptanceCriteria,
   extractRcaBlock,
-  resolveDestination,
   buildRcaMarkdown,
   FAILURE_CLASSES,
   VERDICT_LABELS,

package/src/main/runVerify.cjs

@@ -135,8 +135,8 @@ function extractContent(item) {
  * Parse the run log into a flat sequence of extracted events.
  *
  * Event shapes:
- *   { kind:'tool_use',    seq, toolUseId, toolName, description, command }
- *   { kind:'tool_result', seq, toolUseId, content, isError }
+ *   { kind:'tool_use',    seq, toolUseId, toolName, description, command, parentToolUseId }
+ *   { kind:'tool_result', seq, toolUseId, content, isError, parentToolUseId }
  *   { kind:'result',      seq, subtype, resultText }
  *
  * Non-JSON lines (scheduler metadata "[scheduler] ...") are silently skipped.
@@ -190,6 +190,7 @@ function parseLog(logPath) {
             toolName: item.name ?? '',
             description: item.input?.description ?? '',
             command: item.input?.command ?? '',
+            parentToolUseId: obj.parent_tool_use_id ?? null,
           });
         }
       }
@@ -206,6 +207,7 @@ function parseLog(logPath) {
             toolUseId: item.tool_use_id ?? '',
             content: extractContent(item),
             isError: item.is_error === true,
+            parentToolUseId: obj.parent_tool_use_id ?? null,
           });
         }
       }
@@ -783,6 +785,19 @@ async function verifyRun({ runDir, prdPath, queueEntry, allJobs = [], committedD
       // seen in 58-web-remote-correctness-batch, 2026-06-10).
       if (isHarnessToolError(ev.content)) continue;
 
+      // A tool_result carrying a non-null parent_tool_use_id happened INSIDE a Task
+      // subagent's own execution, not in the main agent's. Subagents do ordinary
+      // exploratory work (greps that exit 1 on no-match, ls on a path that may not
+      // exist) whose failures say nothing about whether the parent run succeeded —
+      // the same false-positive class the Task exemption below already covers for the
+      // content-pattern scan, which sits after this branch and so never reached
+      // is_error. The subagent's OWN final Task tool_result has parentToolUseId ===
+      // null and is still scanned, so a genuinely failed subagent still surfaces.
+      // (Incident: 955-route-epic-create-through-ipc, 2026-08-03 — a fully green,
+      // committed run parked in needs_review over a code-reviewer subagent's
+      // no-match grep at event 450/499.)
+      if (ev.parentToolUseId) continue;
+
       // is_error:true in the final 20% of the transcript.
       if (ev.isError && i >= last20pctStart) {
         const desc = toolUseDesc(events, ev.toolUseId);

package/src/main/scheduler.cjs

@@ -77,7 +77,7 @@ const {
 } = require('./lib/schedulerConfig.cjs');
 const { pickForProject, pickNextBatch, DEFAULT_PROJECT_CWD } = require('./lib/schedulerBatch.cjs');
 const { runDefinitionOfDoneOnDrain } = require('./lib/dodDrainHook.cjs');
-const { fileRcaFeedback, extractRcaBlock } = require('./lib/rcaFeedbackHook.cjs');
+const { writeRcaReport, extractRcaBlock } = require('./lib/rcaReport.cjs');
 const queueHistory = require('./lib/queueHistory.cjs');
 const queueOps = require('./queueOps.cjs');
 // Feedback-auto-PRD sweep — formerly only run by the external scheduler-watchdog
@@ -87,6 +87,7 @@ const queueOps = require('./queueOps.cjs');
 // home-dir layout.
 const { resolvePrdsDirs, resolveArchivedPrdsDirs, resolvePrdWriteDir, listEpicPrdDirs, listArchivedPrdDirs } = require('./lib/prdLocations.cjs');
 const { ensureEpic, appendPrdCreatedEvent, readActiveIndex } = require('./lib/epicMint.cjs');
+const { buildContextDigest } = require('./lib/epicContextDigest.cjs');
 
 // ---------- origin session resolution (PRD 832) ----------
 // An Epic IS a tagged claude session — job rows carry the originating
@@ -1421,8 +1422,8 @@ let heartbeatInterval = null;
 // (The 5-minute feedback sweep that used to piggyback on this heartbeat is
 // gone: it scanned each active project's session-manager-operations/feedback/
 // and auto-queued a /process-feedback PRD. Both the folder and that skill are
-// retired — agents now file a `proposed` Epic that waits for human approval,
-// so there is nothing to sweep for. See lib/rcaFeedbackHook.cjs.)
+// retired, and nothing auto-creates work any more — a parked job is surfaced
+// back into the Epic that authored its PRD instead. See lib/rcaReport.cjs.)
 // In-memory set of slugs currently spawned in this process. Prevents
 // double-spawn when runDueJobs() is called while jobs are in flight.
 const runningSet = new Set();
@@ -1893,6 +1894,42 @@ async function notifyOriginatingTab(job, {
   }
 }
 
+/**
+ * notifyNeedsReview(job, report) → Promise<boolean>
+ *
+ * A job parked in `needs_review` is a question, not a result: something about
+ * the PRD was unclear, unverifiable, or ran past its acceptance criteria.
+ * That question belongs in the conversation that WROTE the PRD, so this
+ * appends a 'response' event to the authoring Epic's own chain (the same
+ * channel notifyOriginatingTab uses for completed/failed, which deliberately
+ * excludes needs_review — isNotifiableTerminalStatus). It resolves the Epic
+ * from the PRD's `sourcePromptId`, falling back to the job's own `epicId`.
+ *
+ * Join-only by construction: appendResponseEventIfKnown refuses an unknown or
+ * non-active session and returns false. Nothing here can create an Epic — if
+ * no open authoring Epic exists, the root-cause report in the run directory
+ * is the whole record and the Scheduler tab is where it surfaces.
+ */
+async function notifyNeedsReview(job, report, {
+  parsePrdRaw = prdParser.parsePrdRaw,
+  appendResponseEvent = appendResponseEventIfKnown,
+} = {}) {
+  try {
+    if (!job || !report || !report.filed) return false;
+    const prd = await parsePrdRaw(prdPathForJob(job)).catch(() => null);
+    const epicId = prd?.sourcePromptId || job.epicId || null;
+    if (!epicId || !job.cwd) {
+      console.log(`[scheduler] notifyNeedsReview: no authoring Epic for ${job.slug}, report only`);
+      return false;
+    }
+    const message = `${report.summary}. Root-cause report: ${report.path}`;
+    return await appendResponseEvent(job.cwd, epicId, message);
+  } catch (e) {
+    console.error('[scheduler] notifyNeedsReview error', job?.slug, e);
+    return false;
+  }
+}
+
 /** Scan the tail of a job's log for the canonical rate-limit signal. We look
  *  at the last 16 KB — final result event always lands at the end.
  *  Uses readTail() so no raw fd lifecycle is needed here. */
@@ -2109,6 +2146,25 @@ async function executeJob(job, runDir, defaultCwd, onPid) {
     }
   }
 
+  // Prepend the Epic's own session digest (PRD 950/958) when this job traces
+  // back to a known Epic — additive only, never mutates the PRD body itself.
+  // A missing/unresolved epicId or a digest build failure is a silent no-op:
+  // the PRD's own body must remain sufficient to complete the job on its own.
+  const digestEpicId = job.epicId ?? job.sourcePromptId ?? null;
+  const originSessionId = resolveOriginSessionId(cwd, digestEpicId);
+  let contextDigestApplied = false;
+  if (originSessionId) {
+    try {
+      const digestText = await buildContextDigest({ cwd, epicId: digestEpicId });
+      if (digestText) {
+        prompt = digestText + '\n\n' + prompt;
+        contextDigestApplied = true;
+      }
+    } catch (e) {
+      safeLog(`[scheduler] context digest build failed (job still dispatches without it): ${e?.message ?? e}\n`);
+    }
+  }
+
   const promptCheck = validatePromptForSpawn(prompt, prdPath);
   if (!promptCheck.ok) {
     safeLog(`[scheduler] ${promptCheck.error}\n`);
@@ -2262,7 +2318,7 @@ async function executeJob(job, runDir, defaultCwd, onPid) {
           sl(`\n[scheduler] ${errMsg}\n`);
           // Sync write: inside a Promise executor callback; must flush meta
           // before resolve() so the spawnJob mutate() that follows sees it.
-          config.writeJsonSync(metaPath, { slug: job.slug, cwd, sessionId, exitCode: -1, error: errMsg, startedAt, finishedAt: Date.now(), durationMs, schedulerBootedAt: SCHEDULER_BOOTED_AT, schedulerCodeSha: SCHEDULER_CODE_SHA });
+          config.writeJsonSync(metaPath, { slug: job.slug, cwd, sessionId, exitCode: -1, error: errMsg, startedAt, finishedAt: Date.now(), durationMs, schedulerBootedAt: SCHEDULER_BOOTED_AT, schedulerCodeSha: SCHEDULER_CODE_SHA, originSessionId, contextDigestApplied });
           resolve({ exitCode: -1, durationMs, error: errMsg, sessionId });
           return;
         }
@@ -2293,6 +2349,7 @@ async function executeJob(job, runDir, defaultCwd, onPid) {
           startedAt, finishedAt: Date.now(), durationMs,
           agentResultSubtype, mappedFromSignal: mappedToSuccess ? signal || `code=${exitCode}` : null,
           schedulerBootedAt: SCHEDULER_BOOTED_AT, schedulerCodeSha: SCHEDULER_CODE_SHA,
+          originSessionId, contextDigestApplied,
         });
         resolve({ exitCode: effectiveCode, durationMs, rateLimited, networkError, sessionId });
       },
@@ -2610,19 +2667,19 @@ async function spawnInvestigation(failedJob, runDir) {
         return;
       }
       sl(`\n[scheduler] investigation exit code=${exitCode}\n`);
-      // Fold the investigation's <RCA> summary into the RCA feedback item already
-      // filed for this job (needs_review jobs only — fileRcaFeedback no-ops when
+      // Fold the investigation's <RCA> summary into the root-cause report already
+      // written for this job (needs_review jobs only — writeRcaReport no-ops when
       // failedJob has no verifierVerdict, e.g. plain 'failed' jobs never got one).
       const investigationText = extractRcaBlock(readTail(investigationLogPath, 64 * 1024));
       if (investigationText) {
-        fileRcaFeedback({
+        writeRcaReport({
           job: failedJob,
           runDir,
           verdict: failedJob.verifierVerdict,
           annotations: failedJob.verifierAnnotations,
           investigationText,
         }).catch((e) => {
-          console.error('[scheduler] fileRcaFeedback (investigation enrichment) error', failedJob.slug, e);
+          console.error('[scheduler] writeRcaReport (investigation enrichment) error', failedJob.slug, e);
         });
       }
       if (fs.existsSync(fixPath)) {
@@ -3006,14 +3063,16 @@ async function spawnJob(job, runId, runDir, defaultCwd) {
     if (needsReviewRcaSnapshot) {
       // Fire-and-forget, mirroring the DoD drain hook: never blocks the status
       // transition, never throws to this caller.
-      fileRcaFeedback({
+      writeRcaReport({
         job: needsReviewRcaSnapshot,
         runDir,
         verdict: needsReviewRcaSnapshot.verifierVerdict,
         annotations: needsReviewRcaSnapshot.verifierAnnotations,
-      }).catch((e) => {
-        console.error('[scheduler] fileRcaFeedback error', job.slug, e);
-      });
+      })
+        .then((report) => notifyNeedsReview(needsReviewRcaSnapshot, report))
+        .catch((e) => {
+          console.error('[scheduler] writeRcaReport error', job.slug, e);
+        });
     }
 
     if (actuallyFailed && failedJobSnapshot) {
@@ -4399,12 +4458,9 @@ const remote = {
         if (candidate && fs.existsSync(candidate)) { dir = d; break; }
       }
       if (!dir) {
-        // Every PRD must join an EXISTING, already-human-approved Epic —
-        // mintIfMissing:false means this never conjures a new one. Only
-        // Epics born from explicit human intent (New Epic UI, or
-        // /propose-epic + Approve & start) may write PRDs; this write path
-        // is not itself a human-intent gate, so it must not become one by
-        // accident.
+        // Every PRD must join an EXISTING, human-created Epic — ensureEpic
+        // is join-only for every caller but the New Epic UI (epicMint.cjs's
+        // SINGLE-CREATOR LAW), so this can never conjure one.
         const { fm } = splitFrontmatter(body);
         try {
           const epic = await ensureEpic(cwd, {
@@ -4415,11 +4471,10 @@ const remote = {
             // a literal-equality join. Any other id (e.g. a PromptTicket.id)
             // simply won't match and this call throws below.
             epicId: fm.sourcePromptId,
-            mintIfMissing: false,
-            // Join-only call (mintIfMissing:false, explicit epicId): the
+            // Join-only call (no mintAuthority, explicit epicId): the
             // explicitEpicId branch in ensureEpic returns before `source` is
             // ever read, so this is a no-op today — kept for symmetry/audit
-            // trail if that join path ever grows a source-touch (PRD 902/905).
+            // trail if that join path ever grows a source-touch.
             source: { producer: 'scheduler-dispatch', prdSlug: slug },
           });
           dir = epic.prdDir;
@@ -4428,7 +4483,7 @@ const remote = {
           return {
             ok: false,
             error: `no existing Epic to join (sourcePromptId=${fm.sourcePromptId ?? 'none'}): ${e?.message ?? 'unknown error'}. `
-              + 'Create the Epic first via the New Epic UI or /propose-epic + Approve & start, then pass its id as sourcePromptId.',
+              + 'Create the Epic first via the New Epic UI, then pass its id as sourcePromptId.',
           };
         }
       }
@@ -4438,7 +4493,7 @@ const remote = {
       if (dir === PRDS_DIR) ensureDirs();
     }
 
-    // writePrd only ever JOINS an existing Epic now (mintIfMissing:false
+    // writePrd only ever JOINS an existing Epic now (no mintAuthority
     // above) — it can never mint one, so there is no orphaned-mint case left
     // to roll back here (contrast the old PRD 825/851 cleanup, removed).
     const resolved = safeSlugPathIn(dir, slug);
@@ -4540,4 +4595,4 @@ function registerAdminRoutes(adminHttp, remoteObj = remote) {
   });
 }
 
-module.exports = { registerScheduleHandlers, attachWindow, init, ROOT, PRDS_DIR, writeQueue, reconcile, reconcileSourcePromptId, allocateParallelGroup, selectHistoryJobs, parsePorcelain, FINISH_PROTOCOL, remote, pickNextBatch, pickForProject, reapDeadRunningJobs, pollRecoveryClearSource, memoryLimitedBatchSize, availableForJobs, reverifyNeedsReview, isRescanCandidate, isPromotableOriginal, selectAutoFixTargets, isEligibleForImmediateAutoFix, resolveRunId, isUnresolvableNeedsReview, healTargetForFix, buildInvestigationPrompt, committedInWindow, computeCommittedDuringRun, classifySigtermWithCommit, isFixPlanSlug, isFixPlanBeyondDepthCap, MAX_INVESTIGATION_DEPTH, forceTickOutcome, applyPauseCleared, detectNetworkErrorInLog, detectRateLimitInLog, classifyFailureOutcome, commitGuardVerdict, TRANSIENT_RETRY_CAP, buildScheduleStatePayload, partitionBootOrphans, applyOrphanOutcome, BOOT_ORPHAN_KILL_GRACE_MS, registerAdminRoutes, notifyOriginatingTab, isNotifiableTerminalStatus, extractResultTextFromLog, candidatePrdsDirs, candidateArchivedPrdsDirs, resolveArchivedPrdStatus, prdDirForCwd, prdPathForJob, archivedPrdPathForJob, archivedTwinExists, findPrdDir, runPrdMigration, shouldSkipInvestigationForCleanRun, archiveCompletedPrd, retireCompletedSlugs, SCHEDULER_BOOTED_AT, SCHEDULER_CODE_SHA, resetJobFields, executeJob, prdArchivedSkipResult };
+module.exports = { registerScheduleHandlers, attachWindow, init, ROOT, PRDS_DIR, writeQueue, reconcile, reconcileSourcePromptId, allocateParallelGroup, selectHistoryJobs, parsePorcelain, FINISH_PROTOCOL, remote, pickNextBatch, pickForProject, reapDeadRunningJobs, pollRecoveryClearSource, memoryLimitedBatchSize, availableForJobs, reverifyNeedsReview, isRescanCandidate, isPromotableOriginal, selectAutoFixTargets, isEligibleForImmediateAutoFix, resolveRunId, isUnresolvableNeedsReview, healTargetForFix, buildInvestigationPrompt, committedInWindow, computeCommittedDuringRun, classifySigtermWithCommit, isFixPlanSlug, isFixPlanBeyondDepthCap, MAX_INVESTIGATION_DEPTH, forceTickOutcome, applyPauseCleared, detectNetworkErrorInLog, detectRateLimitInLog, classifyFailureOutcome, commitGuardVerdict, TRANSIENT_RETRY_CAP, buildScheduleStatePayload, partitionBootOrphans, applyOrphanOutcome, BOOT_ORPHAN_KILL_GRACE_MS, registerAdminRoutes, notifyOriginatingTab, notifyNeedsReview, isNotifiableTerminalStatus, extractResultTextFromLog, candidatePrdsDirs, candidateArchivedPrdsDirs, resolveArchivedPrdStatus, prdDirForCwd, prdPathForJob, archivedPrdPathForJob, archivedTwinExists, findPrdDir, runPrdMigration, shouldSkipInvestigationForCleanRun, archiveCompletedPrd, retireCompletedSlugs, SCHEDULER_BOOTED_AT, SCHEDULER_CODE_SHA, resetJobFields, executeJob, prdArchivedSkipResult };

package/src/preload/api.d.ts

@@ -699,47 +699,6 @@ export interface FilesDuplicateResult { ok: boolean; path?: string; error?: stri
 export interface DocEditResult { ok: boolean; after?: string; error?: string }
 export interface DocEditSessionResult { tabId: string; requestId: string; ok: boolean; after?: string; error?: string }
 
-export interface SearchFileEntry {
-  name: string;
-  path: string;
-  isDirectory: false;
-  isFile: true;
-}
-export interface SearchFilesResult {
-  ok: boolean;
-  files: SearchFileEntry[];
-  error: string | null;
-  usedRipgrep: boolean;
-}
-export interface SearchTextMatch {
-  path: string;
-  line: number;
-  column: number;
-  text: string;
-}
-export interface SearchTextResult {
-  ok: boolean;
-  matches: SearchTextMatch[];
-  error: string | null;
-  usedRipgrep: boolean;
-}
-
-export interface RepoLanguageStats { files: number; lines: number }
-export interface RepoTopDirectory { path: string; fileCount: number; totalLines: number }
-export interface RepoGitStatusSummary { uncommitted: number; branch: string | null }
-export interface RepoAnalyzeResult {
-  ok: true;
-  cwd: string;
-  totalFiles: number;
-  totalLines: number;
-  languageBreakdown: Record<string, RepoLanguageStats>;
-  topDirectories: RepoTopDirectory[];
-  gitStatus: RepoGitStatusSummary;
-  truncated: boolean;
-  durationMs: number;
-}
-export interface RepoAnalyzeError { ok: false; error: string }
-
 export interface WatcherInfo {
   watcherId: string;
   tabId: string;
@@ -1521,13 +1480,6 @@ export interface SessionManagerAPI {
         | { as: 'revealPath'; path: string }
     ) => Promise<{ ok: boolean; opener?: string; error?: string }>;
   };
-  search: {
-    files: (cwd: string, query?: string, opts?: { limit?: number }) => Promise<SearchFilesResult>;
-    text: (cwd: string, query: string, opts?: { limit?: number; caseSensitive?: boolean }) => Promise<SearchTextResult>;
-  };
-  repo: {
-    analyze: (cwd: string) => Promise<RepoAnalyzeResult | RepoAnalyzeError>;
-  };
   history: {
     aggregate: (req?: HistoryAggregateRequest) => Promise<HistoryAggregateResult>;
     scanProjects: () => Promise<SessionScanResult>;
@@ -1765,6 +1717,12 @@ export interface SessionManagerAPI {
      *  in-memory contribution for the cwd; disk stays main's truth, merged
      *  inside the same lock epicMint.cjs's ensureEpic serializes through. */
     mergeActiveIndex: (payload: PromptSessionsMergeActiveIndexPayload) => Promise<PromptSessionsMergeActiveIndexResult>;
+    /** Mints a brand-new 'proposed' Epic through main's own ensureEpic()
+     *  (lib/promptSessionsCreateEpic.cjs) instead of the renderer
+     *  hand-constructing the PromptSession record itself. Unused today —
+     *  additive step 1 of a two-PRD chain; a later PRD routes
+     *  createPromptSession through this. */
+    create: (payload: PromptSessionsCreateEpicPayload) => Promise<PromptSessionsCreateEpicResult>;
   };
 }
 
@@ -1782,6 +1740,25 @@ export interface PromptSessionsMergeActiveIndexResult {
   events: Record<string, unknown[]>;
 }
 
+// ─────────────────────────────────── PromptSessions create-epic (main-side ensureEpic)
+export interface PromptSessionsCreateEpicPayload {
+  cwd: string;
+  goalText: string;
+  tag?: 'feature' | 'bug' | 'discussion' | 'build' | 'project-home-builder' | 'bilko-host-publisher';
+  agentType?: string;
+  source?: {
+    producer: 'new-epic-ui' | 'scheduler-dispatch';
+    prdSlug?: string;
+    runId?: string;
+    sourceTabId?: string;
+  };
+}
+
+export interface PromptSessionsCreateEpicResult {
+  epicId: string;
+  session: Record<string, unknown>;
+}
+
 // ─────────────────────────────────── PromptSession event-appended broadcast
 
 export interface PromptSessionEventAppendedPayload {

package/src/preload/index.cjs

@@ -258,13 +258,6 @@ contextBridge.exposeInMainWorld('api', {
   shell: {
     open: (opts) => ipcRenderer.invoke('shell:open', opts),
   },
-  search: {
-    files: (cwd, query, opts) => ipcRenderer.invoke('search:files', { cwd, query, opts }),
-    text: (cwd, query, opts) => ipcRenderer.invoke('search:text', { cwd, query, opts }),
-  },
-  repo: {
-    analyze: (cwd) => ipcRenderer.invoke('repo:analyze', { cwd }),
-  },
   schedule: {
     state: () => ipcRenderer.invoke('schedule:state'),
     sessionSlots: () => ipcRenderer.invoke('schedule:session-slots'),
@@ -493,5 +486,11 @@ contextBridge.exposeInMainWorld('api', {
      *  renderer-side read-merge-write. Payload carries only this renderer's
      *  own in-memory contribution for the cwd; disk stays main's truth. */
     mergeActiveIndex: (payload) => ipcRenderer.invoke('promptSessions:merge-active-index', payload),
+    /** Mints a brand-new 'proposed' Epic through main's own ensureEpic()
+     *  (lib/promptSessionsCreateEpic.cjs) instead of the renderer
+     *  hand-constructing the PromptSession record itself. Unused today —
+     *  additive step 1 of a two-PRD chain; a later PRD routes
+     *  createPromptSession through this. */
+    create: (payload) => ipcRenderer.invoke('promptSessions:create-epic', payload),
   },
 });