claude-code-session-manager 0.40.3 → 0.41.1

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

@@ -0,0 +1,92 @@
+// opsOwnership.cjs — the single-writer law over a project's ops root.
+// vitest globals (test/beforeEach) — same convention as the other .cjs tests.
+const assert = require('node:assert/strict');
+const path = require('node:path');
+const os = require('node:os');
+const fs = require('node:fs');
+const { parseOpsPath, checkOpsWrite, assertOpsWrite, OWNERS } = require('../opsOwnership.cjs');
+
+const P = '/home/u/Projects/demo/session-manager-operations';
+
+test('parseOpsPath: splits namespace and remainder, ignores non-ops paths', () => {
+  assert.deepEqual(parseOpsPath(`${P}/prompt-sessions/active-index.json`), {
+    inOps: true, namespace: 'prompt-sessions', relative: 'active-index.json',
+  });
+  assert.deepEqual(parseOpsPath(`${P}/scheduler/epics/e1/prds/900-x.md`), {
+    inOps: true, namespace: 'scheduler', relative: 'epics/e1/prds/900-x.md',
+  });
+  assert.equal(parseOpsPath('/home/u/.claude/settings.json').inOps, false);
+  assert.equal(parseOpsPath(null).inOps, false);
+});
+
+test('paths outside any ops root are not governed by ownership', () => {
+  assert.deepEqual(checkOpsWrite('/home/u/.claude/settings.json', undefined), { ok: true, error: null });
+});
+
+test('the owner of a namespace may write it', () => {
+  assert.equal(checkOpsWrite(`${P}/prompt-sessions/active-index.json`, 'epics').ok, true);
+  assert.equal(checkOpsWrite(`${P}/scheduler/state/queue.json`, 'scheduler').ok, true);
+  assert.equal(checkOpsWrite(`${P}/project-brief/brief.json`, 'project-home').ok, true);
+});
+
+test('a non-owner is refused, and the error names the owner', () => {
+  const res = checkOpsWrite(`${P}/project-brief/brief.json`, 'scheduler');
+  assert.equal(res.ok, false);
+  assert.match(res.error, /owned by 'project-home'/);
+  // The exact cross-write this law exists to prevent: another surface
+  // rewriting the Epic store out from under Epics.
+  assert.equal(checkOpsWrite(`${P}/prompt-sessions/psess-1.json`, 'scheduler').ok, false);
+});
+
+test('an undeclared writer is refused (fail-closed)', () => {
+  const res = checkOpsWrite(`${P}/scheduler/state/queue.json`, undefined);
+  assert.equal(res.ok, false);
+  assert.match(res.error, /did not declare a writer/);
+});
+
+test('a namespace with no declared owner is refused, not silently allowed', () => {
+  const res = checkOpsWrite(`${P}/brand-new-thing/state.json`, 'scheduler');
+  assert.equal(res.ok, false);
+  assert.match(res.error, /no declared owner/);
+});
+
+test('the ops root itself is unownable', () => {
+  assert.equal(checkOpsWrite(`${P}/loose-file.json`, 'epics').ok, false);
+});
+
+test('the scheduler delegation covers active-index.json and nothing else', () => {
+  assert.equal(checkOpsWrite(`${P}/prompt-sessions/active-index.json`, 'scheduler').ok, true);
+  // Not the archives, and not a lookalike nested path.
+  assert.equal(checkOpsWrite(`${P}/prompt-sessions/psess-9.json`, 'scheduler').ok, false);
+  assert.equal(checkOpsWrite(`${P}/prompt-sessions/nested/active-index.json`, 'scheduler').ok, false);
+});
+
+test('assertOpsWrite throws for a refused write and is silent for an allowed one', () => {
+  assert.throws(() => assertOpsWrite(`${P}/project-brief/brief.json`, 'epics'), /single-writer law/);
+  assert.doesNotThrow(() => assertOpsWrite(`${P}/project-brief/brief.json`, 'project-home'));
+});
+
+test('every declared owner is a non-empty string (table sanity)', () => {
+  for (const [ns, owner] of Object.entries(OWNERS)) {
+    assert.equal(typeof owner, 'string', `${ns} owner must be a string`);
+    assert.ok(owner.length > 0, `${ns} owner must be non-empty`);
+  }
+});
+
+// Integration: config.cjs must enforce the law on its real write path, not
+// just expose it — a write with the wrong writer has to actually fail.
+test('config.writeJson refuses an ops write from a non-owner', async () => {
+  const config = require('../../config.cjs');
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ops-law-'));
+  config.addAllowedRoot(root);
+  const target = path.join(root, 'session-manager-operations', 'project-brief', 'brief.json');
+
+  await assert.rejects(() => config.writeJson(target, { a: 1 }, { writer: 'epics' }), /single-writer law/);
+  await assert.rejects(() => config.writeJson(target, { a: 1 }), /did not declare a writer/);
+
+  const res = await config.writeJson(target, { a: 1 }, { writer: 'project-home' });
+  assert.equal(res.ok, true);
+  assert.equal(JSON.parse(fs.readFileSync(target, 'utf8')).a, 1);
+
+  fs.rmSync(root, { recursive: true, force: true });
+});

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

@@ -9,6 +9,7 @@ const {
   applyPinEnforcement,
   buildPersistedBrief,
   computeSetPin,
+  computeUpdate,
 } = require('../projectBriefCore.cjs');
 
 test('computeDrift: true only when mtime strictly newer than synthesizedAt', () => {
@@ -140,3 +141,76 @@ test('computeSetPin: pinning freezes current block content, unpinning clears it'
   assert.equal(unpinned.brief.pins.what, false);
   assert.equal(unpinned.brief.pinned.what, null);
 });
+
+// ── computeUpdate: the hand-edit ("maintain") path ────────────────────────
+function baseBrief() {
+  return {
+    version: 1,
+    synthesizedAt: '2026-07-31T00:00:00.000Z',
+    editedAt: null,
+    model: 'sonnet',
+    purpose: 'p',
+    what: ['a'],
+    areas: [{ name: 'x', files: 1, note: '', epic: null, heat: 0.1 }],
+    scope: [],
+    conventions: ['c1'],
+    pins: { what: false, conventions: false },
+    pinned: { what: null, conventions: null },
+  };
+}
+
+test('computeUpdate: errors when there is no brief yet', () => {
+  const res = computeUpdate(null, { what: ['x'] }, '2026-08-01T00:00:00.000Z');
+  assert.equal(res.ok, false);
+  assert.match(res.error, /generate one first/);
+});
+
+test('computeUpdate: rejects an empty patch and non-editable fields', () => {
+  assert.equal(computeUpdate(baseBrief(), {}, 'NOW').ok, false);
+  const res = computeUpdate(baseBrief(), { model: 'opus' }, 'NOW');
+  assert.equal(res.ok, false);
+  assert.match(res.error, /not editable: model/);
+});
+
+test('computeUpdate: rejects field shapes the renderer could not render', () => {
+  assert.equal(computeUpdate(baseBrief(), { purpose: '   ' }, 'NOW').ok, false);
+  assert.equal(computeUpdate(baseBrief(), { what: 'not an array' }, 'NOW').ok, false);
+  assert.equal(computeUpdate(baseBrief(), { conventions: [1, 2] }, 'NOW').ok, false);
+  assert.equal(computeUpdate(baseBrief(), { areas: ['nope'] }, 'NOW').ok, false);
+});
+
+test('computeUpdate: applies the patch, stamps editedAt, leaves other fields alone', () => {
+  const before = baseBrief();
+  const res = computeUpdate(before, { purpose: 'sharper' }, '2026-08-01T00:00:00.000Z');
+  assert.equal(res.ok, true);
+  assert.equal(res.brief.purpose, 'sharper');
+  assert.equal(res.brief.editedAt, '2026-08-01T00:00:00.000Z');
+  assert.deepEqual(res.brief.what, ['a']);
+  assert.equal(res.brief.synthesizedAt, before.synthesizedAt);
+  // purpose is not pinnable — a refresh legitimately re-derives it.
+  assert.equal(res.brief.pins.what, false);
+});
+
+test('computeUpdate: editing a pinnable block auto-pins it with the edited content', () => {
+  const res = computeUpdate(baseBrief(), { what: ['edited one', 'edited two'] }, 'NOW');
+  assert.equal(res.ok, true);
+  assert.equal(res.brief.pins.what, true);
+  assert.deepEqual(res.brief.pinned.what, ['edited one', 'edited two']);
+  assert.equal(res.brief.pins.conventions, false);
+  assert.equal(res.brief.pinned.conventions, null);
+});
+
+test('computeUpdate: an edited block survives the next synthesis via pin enforcement', () => {
+  const edited = computeUpdate(baseBrief(), { conventions: ['hand-written rule'] }, 'NOW').brief;
+  const persisted = buildPersistedBrief({
+    rawBrief: { purpose: 'new', what: ['fresh'], areas: [], scope: [], conventions: ['model rewrote it'] },
+    priorPins: edited.pins,
+    priorPinned: edited.pinned,
+    model: 'sonnet',
+    nowIso: '2026-08-02T00:00:00.000Z',
+    priorEditedAt: edited.editedAt,
+  });
+  assert.deepEqual(persisted.conventions, ['hand-written rule']);
+  assert.deepEqual(persisted.what, ['fresh']);
+  assert.equal(persisted.editedAt, 'NOW');
+});

package/src/main/lib/epicMint.cjs

@@ -21,6 +21,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
 const { resolveEpicPrdWriteDir } = require('./prdLocations.cjs');
+const { assertOpsWrite } = require('./opsOwnership.cjs');
 
 function activeIndexPath(cwd) {
   return path.join(cwd, 'session-manager-operations', 'prompt-sessions', 'active-index.json');
@@ -39,6 +40,9 @@ function readActiveIndex(cwd) {
 }
 
 function writeActiveIndex(cwd, index) {
+  // Single-writer law: prompt-sessions/ is owned by 'epics'; the scheduler
+  // holds a narrow delegation for active-index.json only (opsOwnership.cjs).
+  assertOpsWrite(activeIndexPath(cwd), 'scheduler');
   const file = activeIndexPath(cwd);
   fs.mkdirSync(path.dirname(file), { recursive: true });
   const tmp = `${file}.tmp-${process.pid}`;
@@ -54,8 +58,34 @@ function slugify(text) {
     .slice(0, 48) || 'epic';
 }
 
+// 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
+// there is no await between them today and no real interleaving is possible
+// — but wrapping every read-modify-write in the same lock the sibling module
+// uses means the two files no longer diverge on this pattern, and the lock
+// is already in place if either function's I/O ever becomes async.
+const pendingWritesByPath = new Map();
+
+function withPathLock(lockPath, task) {
+  const prior = pendingWritesByPath.get(lockPath) || Promise.resolve();
+  const settle = () => task();
+  const run = prior.then(settle, settle);
+  pendingWritesByPath.set(
+    lockPath,
+    run.then(
+      () => undefined,
+      () => undefined,
+    ),
+  );
+  return run;
+}
+
 /**
- * ensureEpic(cwd, { goalText, tag?, reuseByGoal? }) → { epicId, prdDir, created }
+ * ensureEpic(cwd, { goalText, tag?, reuseByGoal?, status? }) → Promise<{ epicId, prdDir, created }>
+ *
+ * `status` defaults to 'active'. Pass 'proposed' to file an Epic that waits
+ * for human approval before anything runs.
  *
  * Mints a new Epic — or, with `reuseByGoal`, joins the existing ACTIVE Epic
  * whose goalText matches (used by the recurring feedback sweep so successive
@@ -64,81 +94,125 @@ function slugify(text) {
  * 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 } = {}) {
+function ensureEpic(cwd, { goalText, tag, reuseByGoal = false, epicId: explicitEpicId, status = 'active', openingPrompt = null } = {}) {
   if (!cwd || typeof cwd !== 'string') throw new Error('ensureEpic: cwd is required');
-  const index = readActiveIndex(cwd);
+  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]) {
-    const prdDir = resolveEpicPrdWriteDir(cwd, explicitEpicId);
-    fs.mkdirSync(prdDir, { recursive: true });
-    return { epicId: explicitEpicId, prdDir, created: false };
-  }
+    // 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]) {
+      const prdDir = resolveEpicPrdWriteDir(cwd, explicitEpicId);
+      fs.mkdirSync(prdDir, { recursive: true });
+      return { epicId: explicitEpicId, prdDir, created: false };
+    }
 
-  if (reuseByGoal) {
-    for (const s of Object.values(index.sessions)) {
-      if (s && s.status === 'active' && s.goalText === goalText) {
-        const prdDir = resolveEpicPrdWriteDir(cwd, s.id);
-        fs.mkdirSync(prdDir, { recursive: true });
-        return { epicId: s.id, prdDir, created: false };
+    if (reuseByGoal) {
+      for (const s of Object.values(index.sessions)) {
+        // Match the status being requested so repeat proposals chain into
+        // one proposal instead of spawning a duplicate per trigger.
+        if (s && s.status === status && s.goalText === goalText) {
+          // A PROPOSED Epic has not started, so its opening prompt is still
+          // mutable: a re-trigger carrying richer detail (e.g. the RCA hook's
+          // later investigation pass) enriches the pending proposal in place
+          // rather than filing a duplicate. Never done for an active Epic —
+          // its first turn is already history.
+          if (s.status === 'proposed' && openingPrompt && openingPrompt !== s.openingPrompt) {
+            s.openingPrompt = String(openingPrompt);
+            const chain = index.events[s.id];
+            if (Array.isArray(chain) && chain[0] && chain[0].kind === 'prompt') {
+              chain[0].text = String(openingPrompt);
+            }
+            writeActiveIndex(cwd, index);
+          }
+          const prdDir = resolveEpicPrdWriteDir(cwd, s.id);
+          fs.mkdirSync(prdDir, { recursive: true });
+          return { epicId: s.id, prdDir, created: false };
+        }
       }
     }
-  }
 
-  const epicId = `${slugify(goalText)}-${crypto.randomUUID().slice(0, 8)}`;
-  const now = new Date().toISOString();
-  const session = {
-    id: epicId,
-    cwd,
-    goalText: String(goalText || ''),
-    // Independently minted, never shared with a SessionTab — same invariant
-    // as renderer-created PromptSessions (state/promptSessions.ts).
-    claudeSessionId: crypto.randomUUID(),
-    status: 'active',
-    createdAt: now,
-    completedAt: null,
-    ...(tag ? { tag } : {}),
-  };
-  const firstEvent = {
-    id: crypto.randomUUID(),
-    promptSessionId: epicId,
-    kind: 'prompt',
-    causedByEventId: null,
-    at: now,
-    text: String(goalText || ''),
-  };
-  index.sessions[epicId] = session;
-  index.events[epicId] = [firstEvent];
-  writeActiveIndex(cwd, index);
+    const epicId = `${slugify(goalText)}-${crypto.randomUUID().slice(0, 8)}`;
+    const now = new Date().toISOString();
+    const session = {
+      id: epicId,
+      cwd,
+      goalText: String(goalText || ''),
+      // Independently minted, never shared with a SessionTab — same invariant
+      // as renderer-created PromptSessions (state/promptSessions.ts).
+      claudeSessionId: crypto.randomUUID(),
+      // 'proposed' files the Epic WITHOUT starting it — nothing runs until a
+      // human approves it in the Epics workspace. This is the sink that
+      // replaced the feedback-folder intake (see lib/rcaFeedbackHook.cjs).
+      status,
+      createdAt: now,
+      completedAt: null,
+      ...(tag ? { tag } : {}),
+      // 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) } : {}),
+    };
+    const firstEvent = {
+      id: crypto.randomUUID(),
+      promptSessionId: epicId,
+      kind: 'prompt',
+      causedByEventId: null,
+      at: now,
+      text: String(openingPrompt || goalText || ''),
+    };
+    index.sessions[epicId] = session;
+    index.events[epicId] = [firstEvent];
+    writeActiveIndex(cwd, index);
 
-  const prdDir = resolveEpicPrdWriteDir(cwd, epicId);
-  fs.mkdirSync(prdDir, { recursive: true });
-  return { epicId, prdDir, created: true };
+    const prdDir = resolveEpicPrdWriteDir(cwd, epicId);
+    fs.mkdirSync(prdDir, { recursive: true });
+    return { epicId, prdDir, created: true };
+  });
 }
 
 /**
  * appendPrdCreatedEvent(cwd, epicId, prdSlug) — record a PRD dispatch on the
  * Epic's event chain, FK-linked to the current tail (chain, not tree — the
- * referential-integrity requirement from promptSessions.ts).
+ * referential-integrity requirement from promptSessions.ts). Returns a
+ * Promise<boolean>.
  */
 function appendPrdCreatedEvent(cwd, epicId, prdSlug, text) {
+  return withPathLock(activeIndexPath(cwd), () => {
+    const index = readActiveIndex(cwd);
+    if (!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({
+      id: crypto.randomUUID(),
+      promptSessionId: epicId,
+      kind: 'prd_created',
+      causedByEventId: tail ? tail.id : null,
+      at: new Date().toISOString(),
+      prdSlug,
+      ...(text ? { text } : {}),
+    });
+    index.events[epicId] = chain;
+    writeActiveIndex(cwd, index);
+    return true;
+  });
+}
+
+/**
+ * removeEpic(cwd, epicId) — roll back a freshly-minted Epic when the caller
+ * that minted it (ensureEpic's `created: true`) failed to complete its work
+ * (e.g. the PRD write that motivated the mint never landed). Deletes the
+ * Epic's entry from both active-index.json maps. Never call this for an
+ * Epic ensureEpic reported as joined (`created: false`) — that Epic predates
+ * this call and may carry unrelated history.
+ */
+function removeEpic(cwd, epicId) {
+  if (!cwd || !epicId) return false;
   const index = readActiveIndex(cwd);
   if (!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({
-    id: crypto.randomUUID(),
-    promptSessionId: epicId,
-    kind: 'prd_created',
-    causedByEventId: tail ? tail.id : null,
-    at: new Date().toISOString(),
-    prdSlug,
-    ...(text ? { text } : {}),
-  });
-  index.events[epicId] = chain;
+  delete index.sessions[epicId];
+  delete index.events[epicId];
   writeActiveIndex(cwd, index);
   return true;
 }
 
-module.exports = { ensureEpic, appendPrdCreatedEvent, activeIndexPath, readActiveIndex };
+module.exports = { ensureEpic, appendPrdCreatedEvent, removeEpic, activeIndexPath, readActiveIndex };

package/src/main/lib/opsErrorLog.cjs

@@ -0,0 +1,96 @@
+'use strict';
+
+/**
+ * opsErrorLog.cjs — sole writer of the `logs` ops namespace
+ * (single-writer law, see opsOwnership.cjs). Appends one structured JSONL
+ * line per error to `<cwd>/session-manager-operations/logs/errors-<date>.jsonl`
+ * so errors from every tab/surface land in one common, per-project place
+ * instead of scattered across console.error calls and the machine-global
+ * <userData>/logs/ (which mixes every project together and isn't tagged for
+ * tracing). Every call site funnels through `appendError` — that is what
+ * makes this the sole writer in practice, not just in the OWNERS map.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { assertOpsWrite } = require('./opsOwnership.cjs');
+
+// Same redaction policy as logs.cjs's sanitizeMeta — kept independent (not
+// shared/required) so this module has no dependency on the Electron `app`
+// module and can be unit-tested without a running app.
+const REDACT_KEY = /^(transcript|interim|final|text|content|partial|userText|message|token|secret|password|authorization|cookie|api[_-]?key|access[_-]?token|refresh[_-]?token)$/i;
+
+function sanitizeMeta(meta) {
+  if (!meta || typeof meta !== 'object') return meta;
+  if (Array.isArray(meta)) return meta;
+  const out = {};
+  for (const [k, v] of Object.entries(meta)) {
+    out[k] = REDACT_KEY.test(k) ? '[redacted]' : v;
+  }
+  return out;
+}
+
+function logsDir(cwd) {
+  return path.join(cwd, 'session-manager-operations', 'logs');
+}
+
+function todayFile(cwd) {
+  const d = new Date();
+  const yyyy = d.getFullYear();
+  const mm = String(d.getMonth() + 1).padStart(2, '0');
+  const dd = String(d.getDate()).padStart(2, '0');
+  return path.join(logsDir(cwd), `errors-${yyyy}-${mm}-${dd}.jsonl`);
+}
+
+/**
+ * Append one structured error line, tagged for tracing/analysis.
+ *
+ * @param {{
+ *   cwd: string,           // required — which project's ops root owns this line
+ *   scope: string,         // subsystem name, e.g. 'pty', 'chatRunner', 'voice'
+ *   level?: string,        // default 'error'; 'warn' also accepted
+ *   tabId?: string,        // claudeSessionId of the tab this error belongs to, if any
+ *   epicId?: string,       // Epic id, if this error happened inside an Epic-backed run
+ *   tags?: string[],       // extra caller-supplied tags, merged with the auto-derived ones
+ *   message: string,
+ *   meta?: unknown,
+ * }} entry
+ */
+function appendError({ cwd, scope, level = 'error', tabId, epicId, tags = [], message, meta }) {
+  if (!cwd || typeof cwd !== 'string') return; // no project to attribute this line to — skip
+  const file = todayFile(cwd);
+  try {
+    assertOpsWrite(file, 'logs');
+  } catch {
+    return; // fail-closed, same as every other ops write path — never throw from a log call
+  }
+
+  const autoTags = [
+    `level:${level}`,
+    `scope:${scope || 'unknown'}`,
+    ...(tabId ? [`tab:${tabId}`] : []),
+    ...(epicId ? [`epic:${epicId}`] : []),
+  ];
+  const allTags = Array.from(new Set([...autoTags, ...tags]));
+
+  const line = {
+    ts: new Date().toISOString(),
+    level,
+    scope: scope || 'unknown',
+    tabId: tabId || null,
+    epicId: epicId || null,
+    tags: allTags,
+    message: String(message ?? ''),
+    ...(meta !== undefined ? { meta: sanitizeMeta(meta) } : {}),
+  };
+
+  try {
+    fs.mkdirSync(logsDir(cwd), { recursive: true });
+    // 0o600: same rationale as logs.cjs — error meta can carry local paths /
+    // device labels, keep it off other local users' reach.
+    const fd = fs.openSync(file, 'a', 0o600);
+    try { fs.writeSync(fd, JSON.stringify(line) + '\n'); } finally { fs.closeSync(fd); }
+  } catch { /* best-effort — a logging failure must never break the caller */ }
+}
+
+module.exports = { appendError, logsDir, todayFile };