claude-code-session-manager 0.43.0 → 0.45.0

package/src/main/lib/epicMint.cjs

@@ -51,6 +51,17 @@ function writeActiveIndex(cwd, index) {
   fs.renameSync(tmp, file);
 }
 
+// index.sessions/index.events are plain objects parsed from JSON — bracket
+// lookup with an attacker/agent-supplied key like "__proto__" or
+// "constructor" resolves through the prototype chain to a truthy
+// Object.prototype member even though no such Epic was ever written,
+// bypassing every "does this Epic exist" gate below (including the
+// mintIfMissing:false join-only check that PRD-authoring paths rely on).
+// Always use this instead of `obj[key]`/`!obj[key]` for existence checks.
+function hasOwn(obj, key) {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+
 function slugify(text) {
   return String(text || 'epic')
     .toLowerCase()
@@ -59,6 +70,85 @@ function slugify(text) {
     .slice(0, 48) || 'epic';
 }
 
+const STOPWORDS = new Set([
+  'the', 'a', 'an', 'is', 'of', 'to', 'for', 'and', 'in', 'on', 'at', 'this', 'that',
+]);
+
+// Lowercase, strip punctuation, split on whitespace, drop stopwords — shared
+// by findJoinableEpic's similarity check. Kept standalone so its behavior is
+// independently testable rather than inlined into the Jaccard computation.
+function tokenize(text) {
+  return String(text || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]+/g, ' ')
+    .split(/\s+/)
+    .filter((token) => token && !STOPWORDS.has(token));
+}
+
+function jaccardSimilarity(tokensA, tokensB) {
+  const setA = new Set(tokensA);
+  const setB = new Set(tokensB);
+  if (setA.size === 0 && setB.size === 0) return 0;
+  let intersection = 0;
+  for (const token of setA) {
+    if (setB.has(token)) intersection += 1;
+  }
+  const union = setA.size + setB.size - intersection;
+  return union === 0 ? 0 : intersection / union;
+}
+
+const JOIN_SIMILARITY_THRESHOLD = 0.35;
+
+/**
+ * findJoinableEpicInIndex(index, { goalText, preferEpicId, status }) → { epicId, matchedBy, score? } | null
+ *
+ * Same contract as findJoinableEpic() but takes an already-loaded index —
+ * lets ensureEpic() consult this without a second readActiveIndex() call
+ * inside its own withPathLock critical section. Two strategies, in order:
+ *  1. `preferEpicId` — an explicitly-known origin Epic the caller already has
+ *     in hand. Joined immediately (no similarity check) as long as it exists
+ *     and is still open ('proposed' or 'active') — a 'completed' or unknown
+ *     preferEpicId falls through to strategy 2 rather than joining a dead Epic.
+ *  2. Keyword-similarity — Jaccard token-set overlap between `goalText` and
+ *     every other OPEN Epic's goalText in the same cwd (open = 'proposed' or
+ *     'active', regardless of the specific requested `status` — a proposed
+ *     RCA report and an active one about the same topic are still the same
+ *     underlying issue). Highest score wins if it clears
+ *     JOIN_SIMILARITY_THRESHOLD; otherwise no join. `status` is accepted for
+ *     signature symmetry with ensureEpic()/reuseByGoal but only participates
+ *     in strategy 1's preferEpicId open-check, not the similarity filter.
+ */
+function findJoinableEpicInIndex(index, { goalText, preferEpicId = null, status: _status = 'proposed' } = {}) {
+  if (preferEpicId && hasOwn(index.sessions, preferEpicId)) {
+    const preferred = index.sessions[preferEpicId];
+    if (preferred && (preferred.status === 'proposed' || preferred.status === 'active')) {
+      return { epicId: preferEpicId, matchedBy: 'preferEpicId' };
+    }
+  }
+
+  const candidateTokens = tokenize(goalText);
+  let best = null;
+  for (const s of Object.values(index.sessions)) {
+    if (!s || (s.status !== 'proposed' && s.status !== 'active')) continue;
+    const score = jaccardSimilarity(candidateTokens, tokenize(s.goalText));
+    if (score >= JOIN_SIMILARITY_THRESHOLD && (!best || score > best.score)) {
+      best = { epicId: s.id, matchedBy: 'similarity', score };
+    }
+  }
+  return best;
+}
+
+/**
+ * findJoinableEpic(cwd, { goalText, preferEpicId, status }) → { epicId, matchedBy, score? } | null
+ *
+ * Public entry point for callers outside ensureEpic()'s own critical section
+ * (tests, future PRD 899/900 wiring) — loads the index itself. See
+ * findJoinableEpicInIndex() for the matching logic.
+ */
+function findJoinableEpic(cwd, opts = {}) {
+  return findJoinableEpicInIndex(readActiveIndex(cwd), opts);
+}
+
 // Serializes read-modify-write cycles per active-index.json path, mirroring
 // promptSessionEvents.cjs's own pendingWritesByPath/withPathLock. The current
 // read/write pair below is synchronous (fs.readFileSync/writeFileSync), so
@@ -83,26 +173,43 @@ function withPathLock(lockPath, task) {
 }
 
 /**
- * ensureEpic(cwd, { goalText, tag?, reuseByGoal?, status? }) → Promise<{ epicId, prdDir, created }>
+ * ensureEpic(cwd, { goalText, tag?, reuseByGoal?, status?, openingPrompt?, mintIfMissing?, source?, forceNewEpic? }) → Promise<{ epicId, prdDir, created }>
+ *
+ * Before minting brand-new, the mint branch consults findJoinableEpic() —
+ * minting is the LAST resort, not the default, for automated callers. Pass
+ * `forceNewEpic: true` to skip that check and always mint (the one
+ * legitimate case being explicit human-authored creation).
  *
- * `status` defaults to 'active'. Pass 'proposed' to file an Epic that waits
- * for human approval before anything runs.
+ * `status` defaults to 'proposed' — a fail-safe default so any caller that
+ * forgets to pass it files an Epic that waits for human approval rather than
+ * one that starts running immediately. Pass 'active' explicitly only for the
+ * one legitimate immediate-start path (the New Epic UI's own proposed→active
+ * transition, `promptSessions.ts`'s `approveProposed`).
  *
- * Mints a new Epic — or, with `reuseByGoal`, joins the existing ACTIVE Epic
- * whose goalText matches (used by the recurring feedback sweep so successive
- * sweeps chain into one Epic instead of minting one per tick).
+ * `mintIfMissing` defaults to true for the small set of callers that are
+ * themselves the human-intent gate (propose-epic, the RCA hook, the feedback
+ * sweep — all of which pass `status: 'proposed'`, so "minting" here still
+ * never starts anything without a human's Approve & start). Callers that are
+ * NOT themselves a human-intent gate (an automated PRD-write path acting on
+ * a session's behalf) must pass `mintIfMissing: false` — that path may only
+ * JOIN an Epic that already exists; it throws instead of silently creating a
+ * new one, so no PRD-authoring surface can conjure Epics on its own.
+ *
+ * Mints a new Epic — or, with `reuseByGoal`, joins the existing Epic (of the
+ * same `status`) whose goalText matches (used by the recurring feedback sweep
+ * so successive sweeps chain into one Epic instead of minting one per tick).
  *
  * The Epic's id doubles as its directory name under scheduler/epics/, so the
  * PromptSession ↔ on-disk Epic mapping is 1:1 with no lookup table.
  */
-function ensureEpic(cwd, { goalText, tag, reuseByGoal = false, epicId: explicitEpicId, status = 'active', openingPrompt = null } = {}) {
+function ensureEpic(cwd, { goalText, tag, reuseByGoal = false, epicId: explicitEpicId, status = 'proposed', openingPrompt = null, mintIfMissing = true, source = null, forceNewEpic = false } = {}) {
   if (!cwd || typeof cwd !== 'string') throw new Error('ensureEpic: cwd is required');
   return withPathLock(activeIndexPath(cwd), () => {
     const index = readActiveIndex(cwd);
 
     // A dispatch that already knows its Epic (sourcePromptId frontmatter from
     // an Epic-conversation dispatch) joins it rather than minting a sibling.
-    if (explicitEpicId && index.sessions[explicitEpicId]) {
+    if (explicitEpicId && hasOwn(index.sessions, explicitEpicId)) {
       const prdDir = resolveEpicPrdWriteDir(cwd, explicitEpicId);
       fs.mkdirSync(prdDir, { recursive: true });
       return { epicId: explicitEpicId, prdDir, created: false };
@@ -133,6 +240,23 @@ function ensureEpic(cwd, { goalText, tag, reuseByGoal = false, epicId: explicitE
       }
     }
 
+    if (!mintIfMissing) {
+      throw new Error(
+        `ensureEpic: no existing Epic found (epicId=${explicitEpicId ?? 'none'}) and mintIfMissing is false — `
+        + 'a new Epic can only be created by explicit human intent (New Epic UI, or /propose-epic + Approve & start), '
+        + 'never implicitly by a PRD-authoring path',
+      );
+    }
+
+    if (!forceNewEpic) {
+      const joinable = findJoinableEpicInIndex(index, { goalText, preferEpicId: explicitEpicId, status });
+      if (joinable) {
+        const prdDir = resolveEpicPrdWriteDir(cwd, joinable.epicId);
+        fs.mkdirSync(prdDir, { recursive: true });
+        return { epicId: joinable.epicId, prdDir, created: false };
+      }
+    }
+
     const epicId = `${slugify(goalText)}-${crypto.randomUUID().slice(0, 8)}`;
     const now = new Date().toISOString();
     const session = {
@@ -152,6 +276,9 @@ function ensureEpic(cwd, { goalText, tag, reuseByGoal = false, epicId: explicitE
       // Full body for a proposal whose goalText is only a one-line title;
       // sent verbatim as the first prompt when a human approves it.
       ...(openingPrompt ? { openingPrompt: String(openingPrompt) } : {}),
+      // Structured trace of which automated producer minted this Epic — see
+      // EpicSource in state/promptSessions.ts.
+      ...(source ? { source } : {}),
     };
     const firstEvent = {
       id: crypto.randomUUID(),
@@ -168,7 +295,7 @@ function ensureEpic(cwd, { goalText, tag, reuseByGoal = false, epicId: explicitE
     // Every mint is logged, whether the Epic starts 'proposed' (human gate
     // ahead) or 'active' (started immediately) — this is the trace-back point
     // for "who/what created this Epic" (see auditLog.cjs).
-    appendAuditEvent('epic_mint', { cwd, epicId, status, tag: tag ?? null, goalText: session.goalText });
+    appendAuditEvent('epic_mint', { cwd, epicId, status, tag: tag ?? null, goalText: session.goalText, source: source ?? null });
 
     const prdDir = resolveEpicPrdWriteDir(cwd, epicId);
     fs.mkdirSync(prdDir, { recursive: true });
@@ -185,7 +312,7 @@ function ensureEpic(cwd, { goalText, tag, reuseByGoal = false, epicId: explicitE
 function appendPrdCreatedEvent(cwd, epicId, prdSlug, text) {
   return withPathLock(activeIndexPath(cwd), () => {
     const index = readActiveIndex(cwd);
-    if (!index.sessions[epicId]) return false;
+    if (!hasOwn(index.sessions, epicId)) return false;
     const chain = Array.isArray(index.events[epicId]) ? index.events[epicId] : [];
     const tail = chain.length ? chain[chain.length - 1] : null;
     chain.push({
@@ -214,11 +341,11 @@ function appendPrdCreatedEvent(cwd, epicId, prdSlug, text) {
 function removeEpic(cwd, epicId) {
   if (!cwd || !epicId) return false;
   const index = readActiveIndex(cwd);
-  if (!index.sessions[epicId]) return false;
+  if (!hasOwn(index.sessions, epicId)) return false;
   delete index.sessions[epicId];
   delete index.events[epicId];
   writeActiveIndex(cwd, index);
   return true;
 }
 
-module.exports = { ensureEpic, appendPrdCreatedEvent, removeEpic, activeIndexPath, readActiveIndex };
+module.exports = { ensureEpic, appendPrdCreatedEvent, removeEpic, activeIndexPath, readActiveIndex, findJoinableEpic, tokenize };

package/src/main/lib/rcaFeedbackHook.cjs

@@ -28,7 +28,7 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 const config = require('../config.cjs');
-const { ensureEpic } = require('./epicMint.cjs');
+const { ensureEpic, findJoinableEpic } = require('./epicMint.cjs');
 const { splitFrontmatter } = require('./prdFrontmatter.cjs');
 const { readTail } = require('./fileTail.cjs');
 const { resolvePrdWriteDir } = require('./prdLocations.cjs');
@@ -294,7 +294,7 @@ function buildRcaMarkdown({ job, verdict, meta, logTail, acText, failureClass, i
  * duplicate. A different runId (new run of the same slug) files a new RCA.
  *
  * @param {object} opts
- * @param {{slug: string, cwd?: string, runId: string, exitCode?: number, error?: string}} opts.job
+ * @param {{slug: string, cwd?: string, runId: string, exitCode?: number, error?: string, epicId?: string}} opts.job
  * @param {string} [opts.runDir]   Run directory containing <slug>.log / <slug>.meta.json.
  * @param {string} opts.verdict    Verifier verdict string (e.g. 'uncommitted_changes').
  * @param {Array}  [opts.annotations]  Non-blocking verifier annotations (currently unused
@@ -351,12 +351,33 @@ async function fileRcaFeedback({ job, runDir, verdict, annotations, investigatio
     // 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 },
     });
 
     console.log(`[rca] ${created ? 'proposed' : 'joined'} epic ${epicId} for ${job.slug}`);

package/src/main/lib/sessionSlots.cjs

@@ -1,6 +1,7 @@
 /**
  * sessionSlots.cjs — the Session-Manager-owned machine-wide `claude -p`
- * concurrency pool (2026-07-31 domain-model decision).
+ * concurrency pool (2026-07-31 domain-model decision; made user-configurable
+ * 2026-08-01).
  *
  * Caps and limits belong to Session-Manager, not to any one consumer: the
  * scheduler and chatRunner previously each enforced a private cap (3 and 2),
@@ -8,22 +9,68 @@
  * the 2026-06-10 five-parallel-`claude -p` OOM. Now every subsystem that
  * wants to launch a `claude -p` process REQUESTS a slot here first and
  * releases it when the process settles. There is one pool, sized to the
- * machine (default 3 — CLAUDE.md "Avoid" cap; SM_SESSION_SLOTS overrides,
- * clamped to [1, 3]).
+ * machine (default 5, user-adjustable [0, 10] from the Home tab; 0 pauses new
+ * launches without touching already-running processes — SM_SESSION_SLOTS
+ * still overrides everything for scripted/CI use, clamped to the same
+ * [0, 10] range).
  *
  * Consumers keep their own scheduling policy (FIFO lanes, batch picking,
  * memory gates); this module only answers "may one more process start right
- * now?". Plain Node, no Electron deps, process-local state — all consumers
- * live in the one Electron main process, which is exactly why it can be the
- * arbiter.
+ * now?". Plain Node, no Electron deps, process-local state (the persisted cap
+ * is the one exception — a tiny standalone JSON file, not routed through any
+ * other module's config store) — all consumers live in the one Electron main
+ * process, which is exactly why it can be the arbiter.
  */
 'use strict';
 
 const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const MIN_SLOTS = 0;
+const MAX_SLOTS = 10;
+const DEFAULT_SLOTS = 5;
+
+const CONFIG_PATH = path.join(os.homedir(), '.claude', 'session-manager', 'session-slots-config.json');
+
+function clamp(n) {
+  return Math.min(MAX_SLOTS, Math.max(MIN_SLOTS, n));
+}
+
+function readPersistedCap() {
+  try {
+    const raw = fs.readFileSync(CONFIG_PATH, 'utf8');
+    const parsed = JSON.parse(raw);
+    const cap = Number(parsed.cap);
+    return Number.isFinite(cap) ? clamp(Math.trunc(cap)) : DEFAULT_SLOTS;
+  } catch {
+    return DEFAULT_SLOTS;
+  }
+}
+
+/** Persist a new cap to disk (tmp + rename). Throws on an out-of-range value. */
+function setCap(cap) {
+  const n = Number(cap);
+  if (!Number.isFinite(n) || Math.trunc(n) !== n || n < MIN_SLOTS || n > MAX_SLOTS) {
+    throw new Error(`sessionSlots.setCap: cap must be an integer in [${MIN_SLOTS}, ${MAX_SLOTS}]`);
+  }
+  fs.mkdirSync(path.dirname(CONFIG_PATH), { recursive: true });
+  const tmp = `${CONFIG_PATH}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify({ cap: n }, null, 2));
+  fs.renameSync(tmp, CONFIG_PATH);
+  for (const fn of listeners) {
+    try { fn(); } catch { /* a consumer's pump error is its own problem */ }
+  }
+  return n;
+}
 
 function totalSlots() {
-  const parsed = parseInt(process.env.SM_SESSION_SLOTS || '3', 10);
-  return Math.min(3, Math.max(1, Number.isFinite(parsed) ? parsed : 3));
+  if (process.env.SM_SESSION_SLOTS !== undefined) {
+    const parsed = parseInt(process.env.SM_SESSION_SLOTS, 10);
+    return Number.isFinite(parsed) ? clamp(parsed) : DEFAULT_SLOTS;
+  }
+  return readPersistedCap();
 }
 
 // token → { owner, at }
@@ -51,6 +98,7 @@ function acquire(owner) {
 
 // Release listeners: each consumer registers its own "a slot freed — try to
 // start work" pump so a scheduler release wakes the chat lane and vice versa.
+// Also fired when the cap itself increases (setCap), for the same reason.
 const listeners = new Set();
 function subscribe(fn) {
   listeners.add(fn);
@@ -74,6 +122,10 @@ function snapshot() {
     total: totalSlots(),
     inUse: holders.size,
     holders: [...holders.values()],
+    min: MIN_SLOTS,
+    max: MAX_SLOTS,
+    default: DEFAULT_SLOTS,
+    envOverride: process.env.SM_SESSION_SLOTS !== undefined,
   };
 }
 
@@ -82,4 +134,17 @@ function __resetForTests() {
   holders.clear();
 }
 
-module.exports = { totalSlots, inUse, available, acquire, release, subscribe, snapshot, __resetForTests };
+module.exports = {
+  MIN_SLOTS,
+  MAX_SLOTS,
+  DEFAULT_SLOTS,
+  totalSlots,
+  setCap,
+  inUse,
+  available,
+  acquire,
+  release,
+  subscribe,
+  snapshot,
+  __resetForTests,
+};

package/src/main/scheduler.cjs

@@ -86,7 +86,7 @@ const queueOps = require('./queueOps.cjs');
 // match ROOT/QUEUE_PATH below since both resolve the same ~/.claude/session-manager
 // home-dir layout.
 const { resolvePrdsDirs, resolvePrdWriteDir, listEpicPrdDirs, listArchivedPrdDirs } = require('./lib/prdLocations.cjs');
-const { ensureEpic, appendPrdCreatedEvent, removeEpic, readActiveIndex } = require('./lib/epicMint.cjs');
+const { ensureEpic, appendPrdCreatedEvent, readActiveIndex } = require('./lib/epicMint.cjs');
 
 // ---------- origin session resolution (PRD 832) ----------
 // An Epic IS a tagged claude session — job rows carry the originating
@@ -3710,6 +3710,15 @@ function registerScheduleHandlers() {
   // configuration tab.
   ipcMain.handle('schedule:session-slots', () => sessionSlots.snapshot());
 
+  // Home-tab control for the same pool: user-set cap in [0, 10], default 5.
+  // 0 pauses new claude -p launches machine-wide without killing anything
+  // already running. SM_SESSION_SLOTS (if set) still overrides this at read
+  // time — sessionSlots.snapshot().envOverride tells the UI to disable itself.
+  ipcMain.handle('schedule:set-session-slots', validated(schemas.setSessionSlotsSchema, async (data) => {
+    sessionSlots.setCap(data.cap);
+    return sessionSlots.snapshot();
+  }));
+
   ipcMain.handle('schedule:health', async () => {
     const state = await readQueue();
     const runningJobs = [];
@@ -4178,13 +4187,6 @@ async function init() {
 
 // remote — callable from webRemote.cjs without going through IPC.
 const remote = {
-  async getState() {
-    const state = await readQueue();
-    await reconcile(state);
-    await writeQueue(state);
-    return buildScheduleStatePayload(state, { withPaths: true });
-  },
-
   // `cwd` is optional: prdCreate.cjs's create flow passes the target
   // project's cwd explicitly (the file may not exist yet, so there's
   // nothing for findPrdDir to search for); the renderer's slug-only IPC
@@ -4220,33 +4222,12 @@ const remote = {
     }
   },
 
-  async readLog(slug, runId) {
-    const logPath = path.resolve(path.join(RUNS_DIR, runId, `${slug}.log`));
-    if (!logPath.startsWith(RUNS_DIR + path.sep)) {
-      return { ok: false, error: 'invalid slug or runId' };
-    }
-    try {
-      // realpath resolves symlinks; re-check boundary to block a rogue agent job
-      // that places a symlink inside RUNS_DIR pointing outside the safe root.
-      const real = await fsp.realpath(logPath);
-      if (!real.startsWith(RUNS_DIR + path.sep)) {
-        return { ok: false, error: 'invalid slug or runId' };
-      }
-      const text = await fsp.readFile(real, 'utf8');
-      return { ok: true, text };
-    } catch (e) {
-      return { ok: false, error: e?.message };
-    }
-  },
-
   // `cwd` optional — see readPrd's comment above; prdCreate.cjs's create
   // flow supplies it (the destination project dir for a brand-new file that
   // doesn't exist yet, so findPrdDir would return nothing to write into).
   async writePrd(slug, body, cwd) {
     let dir;
     let epicTrace = null;
-    let epicCreated = false;
-    let epicId = null;
     if (cwd) {
       // Edit-in-place if this slug already lives anywhere under this project
       // (legacy flat dir or any Epic's prds/); otherwise this is a CREATE,
@@ -4258,29 +4239,37 @@ 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.
+        const { fm } = splitFrontmatter(body);
         try {
-          const { fm } = splitFrontmatter(body);
           const epic = await ensureEpic(cwd, {
-            goalText: fm.title || slug,
-            tag: fm.tag,
-            // An Epic-conversation dispatch already has its Epic — join it.
             // fm.sourcePromptId must be an existing Epic's promptSessionId
             // (== its active-index.json sessions key), NOT a
             // PromptTicket.id — epicMint.cjs's ensureEpic looks it up via
             // `index.sessions[explicitEpicId]` (see epicMint.cjs ~line 73),
             // a literal-equality join. Any other id (e.g. a PromptTicket.id)
-            // simply won't match and mints a sibling Epic instead of joining.
+            // simply won't match and this call throws below.
             epicId: fm.sourcePromptId,
+            mintIfMissing: false,
+            // Join-only call (mintIfMissing:false, 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).
+            source: { producer: 'scheduler-dispatch', prdSlug: slug },
           });
           dir = epic.prdDir;
           epicTrace = epic.epicId;
-          epicCreated = epic.created === true;
-          epicId = epic.epicId;
         } catch (e) {
-          // Epic mint must never block a PRD write — fall back to the
-          // legacy flat dir and log loudly.
-          console.error(`[scheduler] ensureEpic failed for ${slug}: ${e?.message}`);
-          dir = prdDirForCwd(cwd);
+          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.',
+          };
         }
       }
       await fsp.mkdir(dir, { recursive: true });
@@ -4289,30 +4278,11 @@ const remote = {
       if (dir === PRDS_DIR) ensureDirs();
     }
 
-    // PRD 825: if this call minted a brand-new Epic (ensureEpic's `created`)
-    // and the write below never lands, don't strand an empty Epic dir —
-    // best-effort remove `<epic>/prds` then `<epic>` itself, only when empty.
-    // PRD 851: also drop the Epic's active-index.json entry (sessions/events)
-    // so an orphaned seed-prompt-only Epic doesn't linger in the Epics nav.
-    // Gated on epicCreated (never fires when ensureEpic joined an existing
-    // Epic) so a pre-existing Epic's history is never touched.
-    const cleanupEmptyMintedEpic = async () => {
-      if (!epicCreated || !epicId) return;
-      try {
-        const entries = await fsp.readdir(dir);
-        if (entries.length === 0) {
-          await fsp.rmdir(dir);
-          const epicRootDir = path.dirname(dir);
-          const epicRootEntries = await fsp.readdir(epicRootDir);
-          if (epicRootEntries.length === 0) await fsp.rmdir(epicRootDir);
-        }
-      } catch { /* best-effort only */ }
-      try { removeEpic(cwd, epicId); } catch { /* best-effort only */ }
-    };
-
+    // writePrd only ever JOINS an existing Epic now (mintIfMissing:false
+    // 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);
     if (!resolved) {
-      await cleanupEmptyMintedEpic();
       return { ok: false, error: 'invalid slug' };
     }
     try {
@@ -4324,23 +4294,20 @@ const remote = {
       // symlink.
       const realParent = await fsp.realpath(path.dirname(resolved));
       if (realParent !== dir && !realParent.startsWith(dir + path.sep)) {
-        await cleanupEmptyMintedEpic();
         return { ok: false, error: 'invalid slug' };
       }
       const existing = await fsp.lstat(resolved).catch(() => null);
       if (existing && existing.isSymbolicLink()) {
-        await cleanupEmptyMintedEpic();
         return { ok: false, error: 'invalid slug' };
       }
       await config.writeTextAtomic(resolved, body, { writer: 'scheduler' });
       const stat = await fsp.stat(resolved);
       if (epicTrace) {
-        // Best-effort: record the dispatch on the minted Epic's event chain.
+        // Best-effort: record the dispatch on the Epic's event chain.
         try { await appendPrdCreatedEvent(cwd, epicTrace, slug); } catch { /* trace only */ }
       }
       return { ok: true, bytesWritten: stat.size };
     } catch (e) {
-      await cleanupEmptyMintedEpic();
       return { ok: false, error: e?.message ?? 'write failed' };
     }
   },
@@ -4378,28 +4345,6 @@ const remote = {
   // reuses the same allocator the file-based /develop authoring path relies
   // on implicitly, rather than re-deriving NN here.
   allocateParallelGroup,
-
-  async runNow() {
-    await clearPause('run-now');
-    runDueJobs().catch((e) => logs.writeLine({
-      level: 'error', scope: 'scheduler',
-      message: 'runDueJobs error (remote:run-now)', meta: { error: e?.message },
-    }));
-    return { ok: true };
-  },
-
-  async setConfig(partial) {
-    const cfg = await mutate((state) => {
-      const { supervisor: supPartial, ...rest } = partial;
-      state.config = { ...state.config, ...rest };
-      if (supPartial !== undefined) {
-        state.config.supervisor = { ...(state.config.supervisor ?? {}), ...supPartial };
-      }
-      return state.config;
-    });
-    await rescheduleTimer();
-    return { ok: true, config: cfg };
-  },
 };
 
 // Registers the two job-management admin HTTP routes (PRD 689 — moved

package/src/main/templates/PRD_AUTHORING.md

@@ -392,7 +392,11 @@ the user may or may not have open.
 
 ### Fallback: writing the PRD file directly
 
-When the app is not running, first mint (or join) an Epic — `node <session-manager-repo>/scripts/mint-epic.cjs <cwd> "<goal>" [feature|bug|discussion]`; its last stdout line is the prds dir — then write `<NN>-<slug>.md` by hand into that
+When the app is not running, first join the EXISTING, already-human-approved Epic you're already
+working inside — `node <session-manager-repo>/scripts/mint-epic.cjs <cwd> <epic-id>`; its last
+stdout line is the prds dir. This only joins; it never creates an Epic, and errors out if
+`<epic-id>` doesn't already exist — get a human to create/approve the Epic first (New Epic UI, or
+`/propose-epic` + Approve & start) if it doesn't. Then write `<NN>-<slug>.md` by hand into that
 `<cwd>/session-manager-operations/scheduler/epics/<epic-id>/prds/` dir (the flat `scheduler/prds/` is RETIRED and auto-archived unexecuted at boot), add `sourcePromptId: <epic-id>` to the frontmatter so the job keeps its Epic linkage, following the frontmatter rules in §6 and the
 body conventions the rest of this guide describes (`# Goal`, `# Acceptance criteria`,
 `# Implementation notes`, `## Engineering standards` inlined verbatim — see `/develop`'s output

package/src/main/webRemote.cjs

@@ -1054,7 +1054,6 @@ function getDispatchMap() {
 
   const { manager: ptyManager } = require('./pty.cjs');
   const sessionsStore = require('./sessionsStore.cjs');
-  const scheduler = require('./scheduler.cjs');
   const { remote: histRemote } = require('./historyAggregator.cjs');
   const chatRunner = require('./chatRunner.cjs');
 
@@ -1095,37 +1094,6 @@ function getDispatchMap() {
       return { ok: true };
     },
 
-    'cmd:schedule:state': async () =>
-      scheduler.remote.getState(),
-
-    'cmd:schedule:read-prd': async (payload) => {
-      const parsed = schemas.scheduleSlug.parse(payload);
-      return scheduler.remote.readPrd(parsed.slug);
-    },
-
-    'cmd:schedule:read-log': async (payload) => {
-      const parsed = schemas.scheduleReadLog.parse(payload);
-      return scheduler.remote.readLog(parsed.slug, parsed.runId);
-    },
-
-    'cmd:schedule:write-prd': async (payload) => {
-      const parsed = schemas.scheduleWritePrd.parse(payload);
-      return scheduler.remote.writePrd(parsed.slug, parsed.body);
-    },
-
-    'cmd:schedule:reset-job': async (payload) => {
-      const parsed = schemas.scheduleSlug.parse(payload);
-      return scheduler.remote.resetJob(parsed.slug);
-    },
-
-    'cmd:schedule:run-now': async () =>
-      scheduler.remote.runNow(),
-
-    'cmd:schedule:set-config': async (payload) => {
-      const parsed = schemas.setConfigSchema.default({}).parse(payload ?? {});
-      return scheduler.remote.setConfig(parsed);
-    },
-
     'cmd:history:aggregate': async (payload) => {
       const parsed = schemas.historyAggregate.parse(payload);
       return histRemote.aggregate(parsed);