claude-code-session-manager 0.43.0 → 0.44.0

package/src/main/lib/__tests__/sessionSlots.test.cjs

@@ -1,36 +1,80 @@
 // sessionSlots.cjs — the Session-Manager-owned machine-wide claude -p pool.
 // vitest globals (test/beforeEach/afterEach) — same convention as the other .cjs tests.
 const assert = require('node:assert');
+const fs = require('node:fs');
 const slots = require('../sessionSlots.cjs');
 
-beforeEach(() => slots.__resetForTests());
+// Same real-homedir convention as queueStore.cjs's own tests — no path override exists
+// for this module, so keep the persisted file removed except where a test deliberately
+// wants it, and restore it to unset afterward.
+const CONFIG_PATH = require('node:path').join(require('node:os').homedir(), '.claude', 'session-manager', 'session-slots-config.json');
+function removeConfig() {
+  try { fs.unlinkSync(CONFIG_PATH); } catch { /* already absent */ }
+}
+
+beforeEach(() => {
+  slots.__resetForTests();
+  removeConfig();
+});
 afterEach(() => {
   slots.__resetForTests();
   delete process.env.SM_SESSION_SLOTS;
+  removeConfig();
 });
 
-test('pool defaults to 3 slots and exhausts', () => {
-  assert.equal(slots.totalSlots(), 3);
-  const t1 = slots.acquire('a');
-  const t2 = slots.acquire('b');
-  const t3 = slots.acquire('c');
-  assert.ok(t1 && t2 && t3);
+test('pool defaults to 5 slots and exhausts', () => {
+  assert.equal(slots.totalSlots(), 5);
+  const tokens = ['a', 'b', 'c', 'd', 'e'].map((o) => slots.acquire(o));
+  assert.ok(tokens.every(Boolean));
   assert.equal(slots.available(), 0);
-  assert.equal(slots.acquire('d'), null, 'fourth acquire must be refused');
-  slots.release(t2);
+  assert.equal(slots.acquire('f'), null, 'sixth acquire must be refused');
+  slots.release(tokens[1]);
   assert.equal(slots.available(), 1);
-  assert.ok(slots.acquire('d'));
+  assert.ok(slots.acquire('f'));
 });
 
-test('SM_SESSION_SLOTS overrides, clamped to [1,3]', () => {
+test('SM_SESSION_SLOTS overrides, clamped to [0, 10]', () => {
   process.env.SM_SESSION_SLOTS = '1';
   assert.equal(slots.totalSlots(), 1);
-  process.env.SM_SESSION_SLOTS = '9';
-  assert.equal(slots.totalSlots(), 3, 'clamped high');
+  process.env.SM_SESSION_SLOTS = '20';
+  assert.equal(slots.totalSlots(), 10, 'clamped high');
   process.env.SM_SESSION_SLOTS = '0';
-  assert.equal(slots.totalSlots(), 1, 'clamped low');
+  assert.equal(slots.totalSlots(), 0, '0 is a legal explicit value (pauses new launches)');
+  process.env.SM_SESSION_SLOTS = '-5';
+  assert.equal(slots.totalSlots(), 0, 'clamped low');
   process.env.SM_SESSION_SLOTS = 'junk';
-  assert.equal(slots.totalSlots(), 3, 'non-numeric falls back to default');
+  assert.equal(slots.totalSlots(), 5, 'non-numeric falls back to default');
+});
+
+test('cap of 0 pauses all new acquisitions without touching existing holders', () => {
+  const t = slots.acquire('a');
+  assert.ok(t);
+  process.env.SM_SESSION_SLOTS = '0';
+  assert.equal(slots.acquire('b'), null);
+  assert.equal(slots.inUse(), 1, 'existing holder is untouched by the pause');
+  slots.release(t);
+  assert.equal(slots.inUse(), 0);
+});
+
+test('setCap persists a value that totalSlots() picks up without an env override', () => {
+  slots.setCap(8);
+  assert.equal(slots.totalSlots(), 8);
+  slots.setCap(0);
+  assert.equal(slots.totalSlots(), 0);
+});
+
+test('setCap rejects out-of-range or non-integer values', () => {
+  assert.throws(() => slots.setCap(11));
+  assert.throws(() => slots.setCap(-1));
+  assert.throws(() => slots.setCap(2.5));
+});
+
+test('setCap notifies subscribers so a raised cap can wake waiting consumers', () => {
+  let notified = 0;
+  const unsub = slots.subscribe(() => { notified += 1; });
+  slots.setCap(7);
+  assert.equal(notified, 1);
+  unsub();
 });
 
 test('release is idempotent and notifies subscribers exactly on real releases', () => {

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