claude-code-session-manager 0.40.2 → 0.41.0

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/opsOwnership.cjs

@@ -0,0 +1,166 @@
+'use strict';
+
+/**
+ * opsOwnership.cjs — THE SINGLE-WRITER LAW for a project's operations root.
+ *
+ * Every per-project operational namespace under
+ * `<projectCwd>/session-manager-operations/<namespace>/` has exactly ONE
+ * owning surface that may write to it. Everyone else reads. Reads are never
+ * restricted — consistency here is about who may *mutate* state, not who may
+ * see it.
+ *
+ * Why: these folders ARE the app's source of truth (Epics, PRDs, queue state,
+ * the Brief). When two surfaces write the same folder, they race through
+ * separate read-modify-write cycles and the later rename silently wins — the
+ * same class of bug that already produced live queue.json rows whose
+ * sourcePromptId and sourceTabId disagree. One writer per namespace removes
+ * the race by construction instead of by convention.
+ *
+ * The law is FAIL-CLOSED: a write into the ops root by an undeclared writer,
+ * or into a namespace with no declared owner, is refused. Adding a new
+ * namespace or a new writer is therefore a deliberate edit to this file — the
+ * ownership map is reviewable in one place rather than implied by whichever
+ * modules happen to call fs.writeFile.
+ *
+ * Enforcement points (every write path into the ops root calls assertOpsWrite):
+ *   - config.cjs writeTextAtomic / writeBinaryAtomic / writeJson / writeJsonSync
+ *   - lib/epicMint.cjs      (raw fs tmp+rename)
+ *   - lib/queueStore.cjs    (raw fs tmp+rename)
+ * Renderer callers declare their writer id through the IPC payload.
+ */
+
+const path = require('node:path');
+
+const OPS_ROOT_DIR = 'session-manager-operations';
+
+/**
+ * namespace → the one writer id allowed to mutate it.
+ *
+ * Writer ids name a SURFACE (the tab/feature that owns the data), not a
+ * module — several modules may implement one surface, but they all write as
+ * that surface, and a surface owns its folder outright.
+ */
+const OWNERS = Object.freeze({
+  // Epics own the PromptSession store: active-index.json + per-Epic archives.
+  'prompt-sessions': 'epics',
+  // The Scheduler owns PRD sources, per-Epic PRD dirs, and queue/history shards.
+  'scheduler': 'scheduler',
+  // Project Home owns the synthesized Brief (generate + hand-edit).
+  'project-brief': 'project-home',
+  // The feedback intake folder — written by the RCA hook and feedback filing.
+  'feedback': 'feedback',
+  // Browser tab scratch saves (DOM captures, screenshots, recorded flows).
+  'browser': 'browser',
+});
+
+/**
+ * Narrow, explicit exceptions to single-writer. Each entry names a second
+ * writer, the exact file it may touch, and why the owner can't do it itself.
+ * Anything not listed here is refused — a delegation must be argued for in
+ * code review, not discovered later in a race.
+ */
+const DELEGATIONS = Object.freeze({
+  'prompt-sessions': Object.freeze([
+    Object.freeze({
+      writer: 'scheduler',
+      // Only this one file, and only its top level.
+      file: 'active-index.json',
+      reason:
+        'The scheduler appends prd_created/response events to the Epic that '
+        + 'spawned a job (promptSessionEvents.cjs, PRD 814) and mints/joins an '
+        + 'Epic when a PRD is created (epicMint.cjs). Both happen in the main '
+        + 'process with no renderer attached, so the Epics surface cannot '
+        + 'perform them. Serialized per-path by each module\'s own write lock.',
+    }),
+  ]),
+});
+
+/**
+ * Split an absolute path into { inOps, namespace, relative }.
+ * `namespace` is the segment directly under session-manager-operations/;
+ * `relative` is the remainder (posix-joined), '' when the path IS the
+ * namespace dir. Returns inOps:false for any path outside an ops root.
+ *
+ * Complexity: O(n) in path segments.
+ */
+function parseOpsPath(absPath) {
+  if (!absPath || typeof absPath !== 'string') return { inOps: false, namespace: null, relative: null };
+  const segs = absPath.split(path.sep).filter(Boolean);
+  const idx = segs.lastIndexOf(OPS_ROOT_DIR);
+  if (idx === -1) return { inOps: false, namespace: null, relative: null };
+  const rest = segs.slice(idx + 1);
+  // A write to the ops root itself carries no namespace — nobody owns it.
+  if (rest.length === 0) return { inOps: true, namespace: null, relative: '' };
+  return { inOps: true, namespace: rest[0], relative: rest.slice(1).join('/') };
+}
+
+/** True when `writer` may write `relative` inside `namespace` by delegation. */
+function isDelegated(namespace, relative, writer) {
+  const entries = DELEGATIONS[namespace];
+  if (!entries) return false;
+  return entries.some((d) => d.writer === writer && d.file === relative);
+}
+
+/**
+ * Decide whether `writer` may write `absPath`. Pure — returns a verdict
+ * rather than throwing, so it can be unit-tested and so callers choose their
+ * own failure mode.
+ *
+ * Paths outside any ops root are allowed here unconditionally: they are
+ * governed by config.cjs's validateWrite boundary, which is a separate
+ * question (may this process write here at all) from ownership (which surface
+ * owns this state).
+ */
+function checkOpsWrite(absPath, writer) {
+  const { inOps, namespace, relative } = parseOpsPath(absPath);
+  if (!inOps) return { ok: true, error: null };
+
+  if (!namespace) {
+    return { ok: false, error: `${OPS_ROOT_DIR}/ itself has no owner — write inside a namespace folder` };
+  }
+
+  const owner = OWNERS[namespace];
+  if (!owner) {
+    return {
+      ok: false,
+      error:
+        `no declared owner for ${OPS_ROOT_DIR}/${namespace}/ — `
+        + `add it to OWNERS in lib/opsOwnership.cjs before writing there`,
+    };
+  }
+
+  if (!writer) {
+    return {
+      ok: false,
+      error:
+        `write to ${OPS_ROOT_DIR}/${namespace}/ did not declare a writer `
+        + `(owner is '${owner}')`,
+    };
+  }
+
+  if (writer === owner) return { ok: true, error: null };
+  if (isDelegated(namespace, relative, writer)) return { ok: true, error: null };
+
+  return {
+    ok: false,
+    error:
+      `'${writer}' may not write ${OPS_ROOT_DIR}/${namespace}/${relative} — `
+      + `that namespace is owned by '${owner}' (single-writer law, `
+      + `lib/opsOwnership.cjs). Read it freely; route writes through the owner.`,
+  };
+}
+
+/** Throwing wrapper used at each enforcement point. */
+function assertOpsWrite(absPath, writer) {
+  const verdict = checkOpsWrite(absPath, writer);
+  if (!verdict.ok) throw new Error(verdict.error);
+}
+
+module.exports = {
+  OPS_ROOT_DIR,
+  OWNERS,
+  DELEGATIONS,
+  parseOpsPath,
+  checkOpsWrite,
+  assertOpsWrite,
+};

package/src/main/lib/prdCreate.cjs

@@ -115,11 +115,19 @@ async function createPrd(input, remote) {
   // joins that treat it as a literal path segment, so an unexpanded `~/...`
   // fails downstream as a bare "invalid slug" instead of a clear cwd error.
   const cwd = expandHome(input.cwd);
+  let realCwd;
   try {
-    config.validatePath(cwd);
+    realCwd = config.validatePath(cwd);
   } catch (e) {
     return { ok: false, status: 400, error: `cwd rejected: ${e?.message ?? 'outside allowed roots'}` };
   }
+  // Register this project's cwd as a write-allowed root (config.cjs's
+  // validateWrite gate). Chat-only Epics (headless claude -p, no Terminal
+  // PTY ever spawned for this cwd) reach this code path without pty.cjs's
+  // addAllowedRoot call ever having run — without this, every PRD write for
+  // such a project fails with "Write outside allowed write boundaries" even
+  // though validatePath (the read boundary) just passed above.
+  config.addAllowedRoot(realCwd);
   input = { ...input, cwd };
 
   const slug = input.slug || deriveSlugFromTitle(input.title);

package/src/main/lib/prdLocations.cjs

@@ -62,6 +62,26 @@ function listEpicPrdDirs(cwd) {
   return dirs;
 }
 
+/**
+ * Every `prds-archived/` dir for one project cwd: the retired flat layout's
+ * sibling archive plus each Epic's own sibling archive. Consumed by the
+ * scheduler's archived-twin stale-queue-row guard, so a PRD archived under
+ * its Epic (the layout every new PRD uses) is still found.
+ */
+function listArchivedPrdDirs(cwd) {
+  const dirs = [path.join(cwd, ...PRD_SUBPATH, '..', 'prds-archived')];
+  let root;
+  try { root = resolveEpicsRoot(cwd); } catch { return dirs; }
+  let entries;
+  try { entries = fs.readdirSync(root, { withFileTypes: true }); } catch { return dirs; }
+  for (const ent of entries) {
+    if (!ent.isDirectory()) continue;
+    const archiveDir = path.join(root, ent.name, 'prds-archived');
+    if (fs.existsSync(archiveDir)) dirs.push(archiveDir);
+  }
+  return dirs;
+}
+
 /**
  * resolvePrdWriteDir(cwd) → `<cwd>/session-manager-operations/scheduler/prds`
  * Pure path join, no I/O. Throws on a missing/non-string cwd so a caller
@@ -158,6 +178,7 @@ module.exports = {
   resolveEpicsRoot,
   resolveEpicPrdWriteDir,
   listEpicPrdDirs,
+  listArchivedPrdDirs,
   deriveEpicIdFromPrdPath,
   PRD_SUBPATH,
   EPICS_SUBPATH,

package/src/main/lib/projectBriefCore.cjs

@@ -8,12 +8,21 @@
  * with plain-object inputs.
  *
  * brief.json shape (see design-mocks/home/DESIGN_SPEC.md "Persistence"):
- *   { version, synthesizedAt, model, purpose, what[], areas[], scope[],
- *     conventions[], pins{what,conventions}, pinned{what,conventions} }
+ *   { version, synthesizedAt, editedAt, model, purpose, what[], areas[],
+ *     scope[], conventions[], pins{what,conventions}, pinned{what,conventions} }
+ *
+ * The file is not write-once: `computeUpdate` is the hand-edit path (the
+ * "maintain" half of generate-and-maintain), so the brief can be corrected
+ * without paying for a full re-synthesis.
  */
 
 const BRIEF_VERSION = 1;
 const PINNABLE_BLOCKS = ['what', 'conventions'];
+/** Fields a caller may hand-edit through `computeUpdate`. Editing a PINNABLE
+ *  block also auto-pins it, so the next refresh cannot silently undo the edit;
+ *  the derived blocks (areas/scope) are re-synthesized on every refresh by
+ *  design, so edits to them are a stopgap, not a source of truth. */
+const EDITABLE_FIELDS = ['purpose', 'what', 'areas', 'scope', 'conventions'];
 
 /** true when a source's mtime is strictly newer than the brief's synthesizedAt. */
 function computeDrift(mtimeMs, synthesizedAtMs) {
@@ -131,12 +140,15 @@ function applyPinEnforcement(rawBrief, priorPins, priorPinned) {
 }
 
 /** Full persisted-shape builder: stamps version/synthesizedAt/model on top of
- *  the pin-enforced content. `nowIso` is passed in — never computed here. */
-function buildPersistedBrief({ rawBrief, priorPins, priorPinned, model, nowIso }) {
+ *  the pin-enforced content. `nowIso` is passed in — never computed here.
+ *  `priorEditedAt` carries forward so a refresh doesn't erase the record that
+ *  the (pinned, therefore preserved) blocks were hand-edited. */
+function buildPersistedBrief({ rawBrief, priorPins, priorPinned, model, nowIso, priorEditedAt = null }) {
   const enforced = applyPinEnforcement(rawBrief, priorPins, priorPinned);
   return {
     version: BRIEF_VERSION,
     synthesizedAt: nowIso,
+    editedAt: priorEditedAt || null,
     model,
     purpose: enforced.purpose,
     what: enforced.what,
@@ -163,9 +175,61 @@ function computeSetPin(currentBrief, block, pinned) {
   return { ok: true, brief: { ...currentBrief, pins: nextPins, pinned: nextPinned } };
 }
 
+/** Per-field shape guard for a hand-edit patch. Mirrors validateBriefShape's
+ *  strictness so an edit can never write a brief the renderer can't render. */
+function validateUpdateField(field, value) {
+  if (field === 'purpose') {
+    if (typeof value !== 'string' || !value.trim()) return 'purpose must be a non-empty string';
+    return null;
+  }
+  if (!Array.isArray(value)) return `${field} must be an array`;
+  if (field === 'what' || field === 'conventions') {
+    if (value.some((v) => typeof v !== 'string')) return `${field} must be an array of strings`;
+    return null;
+  }
+  if (value.some((v) => !v || typeof v !== 'object' || Array.isArray(v))) return `${field} must be an array of objects`;
+  return null;
+}
+
+/**
+ * Pure hand-edit transform. Given the current brief (or null), a patch of
+ * editable fields, and `nowIso`, returns the next brief with the patch applied
+ * and `editedAt` stamped. Any edited PINNABLE block is auto-pinned and its
+ * frozen copy set to the new content, so the next refresh preserves the edit
+ * instead of overwriting it. Returns {ok:false, error} on a missing brief,
+ * an unknown/empty patch, or a field whose shape would break the renderer.
+ *
+ * Complexity: O(n) in the patched arrays' lengths.
+ */
+function computeUpdate(currentBrief, patch, nowIso) {
+  if (!currentBrief) return { ok: false, error: 'no brief to edit yet — generate one first' };
+  if (!patch || typeof patch !== 'object' || Array.isArray(patch)) return { ok: false, error: 'patch must be an object' };
+
+  const fields = Object.keys(patch);
+  if (fields.length === 0) return { ok: false, error: 'patch is empty' };
+  const unknown = fields.filter((f) => !EDITABLE_FIELDS.includes(f));
+  if (unknown.length) return { ok: false, error: `not editable: ${unknown.join(', ')}` };
+  for (const f of fields) {
+    const err = validateUpdateField(f, patch[f]);
+    if (err) return { ok: false, error: err };
+  }
+
+  const next = { ...currentBrief, ...patch, editedAt: nowIso };
+  next.pins = { what: false, conventions: false, ...(currentBrief.pins || {}) };
+  next.pinned = { what: null, conventions: null, ...(currentBrief.pinned || {}) };
+  for (const block of PINNABLE_BLOCKS) {
+    if (fields.includes(block)) {
+      next.pins[block] = true;
+      next.pinned[block] = patch[block];
+    }
+  }
+  return { ok: true, brief: next };
+}
+
 module.exports = {
   BRIEF_VERSION,
   PINNABLE_BLOCKS,
+  EDITABLE_FIELDS,
   computeDrift,
   buildSources,
   buildSynthesisPrompt,
@@ -173,4 +237,6 @@ module.exports = {
   applyPinEnforcement,
   buildPersistedBrief,
   computeSetPin,
+  validateUpdateField,
+  computeUpdate,
 };

package/src/main/lib/queueStore.cjs

@@ -33,6 +33,7 @@ const fsp = require('node:fs/promises');
 const path = require('node:path');
 const os = require('node:os');
 const { allProjectCwds, activeProjectCwds } = require('../../../scripts/lib/activeSessions.cjs');
+const { assertOpsWrite } = require('./opsOwnership.cjs');
 
 const MACHINE_STATE_PATH = path.join(os.homedir(), '.claude', 'session-manager', 'scheduler-machine.json');
 const LEGACY_QUEUE_PATH = path.join(os.homedir(), '.claude', 'session-manager', 'scheduled-plans', 'queue.json');
@@ -52,6 +53,7 @@ function projectHistoryPath(cwd) {
 }
 
 function writeJsonAtomicSync(file, value) {
+  assertOpsWrite(file, 'scheduler');
   fs.mkdirSync(path.dirname(file), { recursive: true });
   const tmp = `${file}.tmp-${process.pid}`;
   fs.writeFileSync(tmp, JSON.stringify(value, null, 2));
@@ -59,6 +61,7 @@ function writeJsonAtomicSync(file, value) {
 }
 
 async function writeJsonAtomic(file, value) {
+  assertOpsWrite(file, 'scheduler');
   await fsp.mkdir(path.dirname(file), { recursive: true });
   const tmp = `${file}.tmp-${process.pid}`;
   await fsp.writeFile(tmp, JSON.stringify(value, null, 2));