claude-code-session-manager 0.40.3 → 0.41.0

package/src/main/chatRunner.cjs

@@ -18,13 +18,11 @@
  * Public surface:
  *   run({ tabId, sessionId, prompt, cwd, resume, silent }): void  — fire-and-forget enqueue.
  *     Both silent (PRD 470) and manual runs go through the same CONCURRENCY_CAP FIFO lane.
- *     Silent runs additionally suppress the six turn-affecting broadcasts + recordExchange
- *     (see probeContextUsage below).
+ *     Silent runs additionally suppress the six turn-affecting broadcasts + recordExchange.
  *   cancel(tabId): Promise<void>  — resolves once the cancelled run fully settles
  *   parseStopSignal(finalText): { questions: string[] } | null     — exported for reuse
  *   parseContextUsageMarkdown(text): { usedTokens, totalTokens, usedPct, categories } | null
  *                                                                    — pure parser for `/context`
- *   probeContextUsage({ tabId, sessionId, cwd }): void  — fire-and-forget silent `/context` probe
  *   STOP_SENTINEL: string                                           — exported for tests
  *   __setExecutor(fn): void                                         — test seam
  *
@@ -42,8 +40,6 @@
  *                           landed before verifying/retrying
  *   chat:run:notice     { tabId, sessionId, message }        — informational, not terminal
  *                         (also fires at 80% of the kill ceiling as a wrap-up nudge)
- *   chat:context-usage  { tabId, sessionId, usedTokens, totalTokens, usedPct, categories }
- *                                                             — result of a silent `/context` probe
  */
 
 const { spawn } = require('node:child_process');
@@ -184,41 +180,6 @@ function parseContextUsageMarkdown(text) {
   return { usedTokens, totalTokens, usedPct, categories };
 }
 
-/**
- * Fire-and-forget silent probe of the resumed session's context usage. Reuses
- * the normal `run()` queue/lane (resume: true, silent: true) so it can never
- * race a real chat run against the same `--resume sessionId`. Broadcasts
- * `chat:context-usage` on success; logs (never throws/broadcasts) on a parse
- * failure.
- *
- * @param {{ tabId: string, sessionId: string, cwd: string }} params
- */
-function probeContextUsage({ tabId, sessionId, cwd }) {
-  run({
-    tabId,
-    sessionId,
-    prompt: '/context',
-    cwd,
-    resume: true,
-    silent: true,
-    onSilentResult: (text) => {
-      const parsed = parseContextUsageMarkdown(text);
-      if (!parsed) {
-        console.error('[chatRunner] parseContextUsageMarkdown failed to parse /context probe output');
-        return;
-      }
-      broadcast('chat:context-usage', {
-        tabId,
-        sessionId,
-        usedTokens: parsed.usedTokens,
-        totalTokens: parsed.totalTokens,
-        usedPct: parsed.usedPct,
-        categories: parsed.categories,
-      });
-    },
-  });
-}
-
 // ─── MCP consent-denial detection ──────────────────────────────────────────
 // Best-effort substring heuristic over known CLI phrasing — NOT a documented
 // stream-json schema field. Confirmed by extracting strings from the compiled
@@ -686,7 +647,7 @@ function executeRun({ tabId, sessionId, prompt, cwd, resume, silent, onSilentRes
         if (event.subtype === 'success') {
           if (silent) {
             // Silent probe: no turn broadcast, no recordExchange — just hand
-            // the final text to whoever enqueued the probe (e.g. probeContextUsage).
+            // the final text to whoever enqueued the probe.
             emitTerminal('chat:run:complete', { tabId, sessionId, finalMessage: text });
             if (typeof onSilentResult === 'function') onSilentResult(text);
           } else {
@@ -888,10 +849,6 @@ function registerChatHandlers() {
     await cancel(tabId);
   });
 
-  ipcMain.handle('chat:probe-context', validated(schemas.chatProbeContext, async ({ tabId, sessionId, cwd }) => {
-    probeContextUsage({ tabId, sessionId, cwd });
-    return { ok: true };
-  }));
 }
 
 module.exports = {
@@ -903,7 +860,6 @@ module.exports = {
   parseStopSignal,
   splitStopSignal,
   parseContextUsageMarkdown,
-  probeContextUsage,
   STOP_SENTINEL,
   CHAT_MODE_TRUTH_INSTRUCTION,
   KILL_CEILING_MS,

package/src/main/config.cjs

@@ -19,6 +19,7 @@ const fs = require('node:fs');
 const fsp = require('node:fs/promises');
 const path = require('node:path');
 const os = require('node:os');
+const { assertOpsWrite } = require('./lib/opsOwnership.cjs');
 const chokidar = require('chokidar');
 const logs = require('./logs.cjs');
 const { sendIfAlive } = require('./lib/sendToRenderer.cjs');
@@ -219,6 +220,7 @@ async function readText(abs) {
 async function writeTextAtomic(abs, text, opts = {}) {
   const real = validatePath(expandHome(abs));
   validateWrite(real);
+  assertOpsWrite(real, opts.writer);
   const dir = path.dirname(real);
   await fsp.mkdir(dir, { recursive: true });
   const tmp = `${real}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
@@ -242,9 +244,10 @@ async function writeTextAtomic(abs, text, opts = {}) {
  * Binary-safe sibling of writeTextAtomic — same validate + tmp+rename flow,
  * for callers (screenshot capture) whose payload is a Buffer, not utf8 text.
  */
-async function writeBinaryAtomic(abs, buffer) {
+async function writeBinaryAtomic(abs, buffer, opts = {}) {
   const real = validatePath(expandHome(abs));
   validateWrite(real);
+  assertOpsWrite(real, opts.writer);
   const dir = path.dirname(real);
   await fsp.mkdir(dir, { recursive: true });
   const tmp = `${real}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
@@ -259,9 +262,9 @@ async function writeBinaryAtomic(abs, buffer) {
   return { ok: true, mtimeMs: stat.mtimeMs };
 }
 
-async function writeJson(abs, data) {
+async function writeJson(abs, data, opts = {}) {
   const pretty = JSON.stringify(data, null, 2) + '\n';
-  return writeTextAtomic(abs, pretty);
+  return writeTextAtomic(abs, pretty, opts);
 }
 
 /**
@@ -269,9 +272,10 @@ async function writeJson(abs, data) {
  * an event-loop yield would deadlock the caller. Use writeJson/writeTextAtomic
  * for everything else.
  */
-function writeJsonSync(abs, data) {
+function writeJsonSync(abs, data, opts = {}) {
   const real = validatePath(expandHome(abs));
   validateWrite(real);
+  assertOpsWrite(real, opts.writer);
   const dir = path.dirname(real);
   fs.mkdirSync(dir, { recursive: true });
   const tmp = `${real}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
@@ -432,8 +436,10 @@ function registerConfigHandlers() {
   const { schemas: s, validated: v } = require('./ipcSchemas.cjs');
   ipcMain.handle('config:read-json', v(s.configPath, ({ path: p }) => readJson(p)));
   ipcMain.handle('config:read-text', v(s.configPath, ({ path: p }) => readText(p)));
-  ipcMain.handle('config:write-json', v(s.configWriteJson, ({ path: p, data }) => writeJson(p, data)));
-  ipcMain.handle('config:write-text', v(s.configWriteText, ({ path: p, text }) => writeTextAtomic(p, text)));
+  // `writer` is the renderer's declared owner id for the single-writer law
+  // (lib/opsOwnership.cjs). Ignored outside the ops root; required inside it.
+  ipcMain.handle('config:write-json', v(s.configWriteJson, ({ path: p, data, writer }) => writeJson(p, data, { writer })));
+  ipcMain.handle('config:write-text', v(s.configWriteText, ({ path: p, text, writer }) => writeTextAtomic(p, text, { writer })));
   ipcMain.handle('config:list-dir', v(s.configListDir, ({ path: p, opts }) => listDir(p, opts || {})));
   ipcMain.handle('config:exists', v(s.configPath, ({ path: p }) => exists(p)));
   ipcMain.handle('config:parse-imports', v(s.configParseImports, async ({ path: p }) => {

package/src/main/docEdit.cjs

@@ -169,13 +169,12 @@ const SESSION_EDIT_TIMEOUT_MS = 120_000;
 /**
  * Route a doc edit into an already-open, currently-idle chat session (PRD 680)
  * instead of an isolated one-shot `claude -p`. Reuses chatRunner.cjs's silent/
- * resumed run path verbatim (the same mechanism `probeContextUsage` uses) so
- * the edit lands as one more turn of the session's own transcript.
+ * resumed run path verbatim so the edit lands as one more turn of the
+ * session's own transcript.
  *
  * Fire-and-forget: the result reaches the renderer via a `docedit:session-result`
  * broadcast (tagged with `requestId`) once chatRunner's onSilentResult fires, or
- * once SESSION_EDIT_TIMEOUT_MS elapses without one (see above) — the same
- * indirection probeContextUsage uses for `chat:context-usage`, plus the bound.
+ * once SESSION_EDIT_TIMEOUT_MS elapses without one (see above).
  *
  * @param {{ tabId: string, sessionId: string, cwd: string, before: string, instruction: string, documentText?: string, requestId: string }} params
  */

package/src/main/index.cjs

@@ -29,6 +29,7 @@ const scheduler = require('./scheduler.cjs');
 const { createAdminHttp } = require('./lib/localAdminHttp.cjs');
 const prdCreate = require('./lib/prdCreate.cjs');
 const chatRunner = require('./chatRunner.cjs');
+const promptSessionEvents = require('./promptSessionEvents.cjs');
 const adminHttp = createAdminHttp();
 scheduler.registerAdminRoutes(adminHttp);
 prdCreate.registerAdminRoute(adminHttp, scheduler.remote);
@@ -55,6 +56,7 @@ const schedulerConfig = require('./lib/schedulerConfig.cjs');
 const memoryTool = require('./memoryTool.cjs');
 const { registerMemoryAggregateIpc } = require('./memoryAggregate.cjs');
 const { registerProjectBriefIpc } = require('./projectBrief.cjs');
+const promptSessionTranscript = require('./promptSessionTranscript.cjs');
 const agentMemory = require('./agentMemory.cjs');
 const git = require('./git.cjs');
 const filesIpc = require('./files.cjs');
@@ -307,6 +309,7 @@ async function rebootApp() {
     watchers.attachWindow(mainWindow);
     pluginInstall.attachWindow(mainWindow);
     chatRunner.attachWindow(mainWindow);
+    promptSessionEvents.attachWindow(mainWindow);
     attachDocEditWindow(mainWindow);
     rebooting = false;
     return;
@@ -772,6 +775,14 @@ pluginInstall.registerPluginInstallHandlers();
 memoryTool.registerMemoryHandlers();
 registerMemoryAggregateIpc();
 registerProjectBriefIpc();
+ipcMain.handle('promptSessionTranscript:append', validated(schemas.promptSessionTranscriptAppend, async ({ cwd, epicId, role, text, at, eventId }) => {
+  const ok = await promptSessionTranscript.appendTurn(cwd, epicId, { role, text, at, eventId });
+  return { ok };
+}));
+ipcMain.handle('promptSessionTranscript:read', validated(schemas.promptSessionTranscriptRead, async ({ cwd, epicId, limit }) => {
+  const turns = await promptSessionTranscript.readTurns(cwd, epicId, { limit });
+  return { turns };
+}));
 agentMemory.registerAgentMemoryHandlers();
 git.register(ipcMain);
 filesIpc.registerFilesHandlers();
@@ -1092,6 +1103,7 @@ app.whenReady().then(async () => {
   pluginInstall.attachWindow(mainWindow);
   webRemote.attachWindow(mainWindow);
   chatRunner.attachWindow(mainWindow);
+  promptSessionEvents.attachWindow(mainWindow);
   attachDocEditWindow(mainWindow);
   // Scheduler ownership (PRD 834): exactly one instance machine-wide runs
   // scheduler mutation (boot reconciliation, ticking, sweep, supervisor) and

package/src/main/ipcSchemas.cjs

@@ -118,6 +118,8 @@ const browserSaveRecording = z.object({
 const browserSaveBinary = z.object({
   path: z.string().min(1).max(4096),
   base64: z.string().min(1).max(50_000_000),
+  // Single-writer law (lib/opsOwnership.cjs) — required for ops-root paths.
+  writer: z.string().min(1).max(64).optional(),
 });
 
 // PRD 410: replay a recorded step list against a live view. The renderer
@@ -183,14 +185,20 @@ const transcriptUsageFor = z.object({
 // ──────────────────────────────────────────── Config
 const configPath = z.object({ path: z.string().min(1).max(4096) });
 
+// `writer` carries the renderer's declared owner id for the single-writer law
+// (lib/opsOwnership.cjs). Optional on the wire because most writes target
+// ~/.claude, not a project ops root; writes INSIDE the ops root are refused
+// when it is absent or wrong.
 const configWriteJson = z.object({
   path: z.string().min(1).max(4096),
   data: z.unknown(),
+  writer: z.string().min(1).max(64).optional(),
 });
 
 const configWriteText = z.object({
   path: z.string().min(1).max(4096),
   text: z.string(),
+  writer: z.string().min(1).max(64).optional(),
 });
 
 const configListDir = z.object({
@@ -284,10 +292,12 @@ const schedulerCreatePrd = z.object({
   // Explicit ordering (PRD 832): slugs that must complete before this PRD
   // becomes eligible. Written to frontmatter as `dependsOn: [a, b]`.
   dependsOn: z.array(z.string().min(1).max(160).regex(/^[A-Za-z0-9][\w.-]*$/)).max(20).optional(),
-  // Originating PromptTicket.id (PRD 748) when this PRD was authored from a
-  // ticket classified 'develop' (PRD 749) — traces the PRD back to the
-  // prompt that spawned it. Same newline-injection guard as title/cwd since
-  // it also becomes a frontmatter value.
+  // An EXISTING Epic's promptSessionId (PRD 748) — NOT a PromptTicket.id.
+  // ensureEpic() (epicMint.cjs) joins the Epic whose active-index.json
+  // sessions key literally equals this value; the renderer only ever sends
+  // PromptTicket.promptSessionId here (see state/chat.ts), never
+  // PromptTicket.id — those are distinct fields. Same newline-injection
+  // guard as title/cwd since it also becomes a frontmatter value.
   sourcePromptId: z.string().min(1).max(128).regex(NO_NEWLINE_RE, 'must not contain newlines').optional(),
   // Originating tab id (PRD 761) — used at job completion to route a status
   // prompt back into the chat tab that queued this PRD, via
@@ -425,6 +435,40 @@ const projectBriefSetPin = z.object({
   block: PROJECT_BRIEF_BLOCK,
   pinned: z.boolean(),
 }).strict();
+// Hand-edit patch. Only bounds the wire shape (sizes + which keys exist);
+// per-field shape is enforced by projectBriefCore.validateUpdateField so the
+// rule lives in one unit-tested place. At least one key is required.
+const PROJECT_BRIEF_TEXT = z.string().max(20_000);
+const projectBriefUpdate = z.object({
+  cwd: z.string().min(1).max(4096),
+  patch: z.object({
+    purpose: PROJECT_BRIEF_TEXT.optional(),
+    what: z.array(PROJECT_BRIEF_TEXT).max(50).optional(),
+    conventions: z.array(PROJECT_BRIEF_TEXT).max(100).optional(),
+    areas: z.array(z.record(z.unknown())).max(100).optional(),
+    scope: z.array(z.record(z.unknown())).max(200).optional(),
+  }).strict().refine((p) => Object.keys(p).length > 0, { message: 'patch is empty' }),
+}).strict();
+
+// ──────────────────────────────────────────── Prompt session transcript
+// (durable full-text turn store, PRD 863). cwd/epicId are only bounded for
+// wire shape here — real path safety is config.cjs's validatePath/
+// validateWrite inside promptSessionTranscript.cjs.
+const PROMPT_SESSION_EPIC_ID_RE = /^[A-Za-z0-9._-]{1,128}$/;
+const PROMPT_SESSION_TRANSCRIPT_ROLE = z.enum(['user', 'assistant']);
+const promptSessionTranscriptAppend = z.object({
+  cwd: z.string().min(1).max(4096),
+  epicId: z.string().regex(PROMPT_SESSION_EPIC_ID_RE),
+  role: PROMPT_SESSION_TRANSCRIPT_ROLE,
+  text: z.string().max(2_000_000),
+  at: z.string().max(64).optional(),
+  eventId: z.string().max(128).optional(),
+}).strict();
+const promptSessionTranscriptRead = z.object({
+  cwd: z.string().min(1).max(4096),
+  epicId: z.string().regex(PROMPT_SESSION_EPIC_ID_RE),
+  limit: z.number().int().positive().max(10_000).optional(),
+}).strict();
 
 // ──────────────────────────────────────────── Per-subagent memory
 // Distinct from the workspace-scoped Memory tool: agentMemory is keyed by
@@ -516,12 +560,6 @@ const chatCancel = z.object({
   tabId: z.string().min(1).max(128),
 });
 
-const chatProbeContext = z.object({
-  tabId: z.string().min(1).max(128),
-  sessionId: z.string().min(1).max(128),
-  cwd: z.string().min(1).max(4096),
-});
-
 const chatClassifyTicket = z.object({
   text: z.string().min(1).refine(
     (s) => Buffer.byteLength(s, 'utf8') <= CHAT_PROMPT_MAX_BYTES,
@@ -817,6 +855,9 @@ module.exports = {
     memoryStale,
     projectBriefCwd,
     projectBriefSetPin,
+    projectBriefUpdate,
+    promptSessionTranscriptAppend,
+    promptSessionTranscriptRead,
     agentMemoryList,
     agentMemoryGet,
     agentMemorySet,
@@ -830,7 +871,6 @@ module.exports = {
     docEditRunInSession,
     chatRun,
     chatCancel,
-    chatProbeContext,
     chatClassifyTicket,
     chatExternalSend,
     exchangesList,

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');
+});