claude-code-session-manager 0.39.4 → 0.40.1

package/src/main/__tests__/transcriptsUsageFor.test.cjs

@@ -0,0 +1,89 @@
+/**
+ * transcriptsUsageFor.test.cjs — unit tests for transcripts.cjs's usageFor(),
+ * the batched token-usage reader backing the `transcript:usageFor` IPC (Epics
+ * workspace tokens metric).
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/transcriptsUsageFor.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeEach, afterEach } from 'vitest';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const { usageFor, transcriptPath } = require('../transcripts.cjs');
+
+let cwd;
+
+beforeEach(() => {
+  cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-usage-test-'));
+});
+
+afterEach(() => {
+  fs.rmSync(cwd, { recursive: true, force: true });
+});
+
+function writeTranscript(cwdArg, sessionId, lines) {
+  const filePath = transcriptPath(cwdArg, sessionId);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, lines.map((l) => JSON.stringify(l)).join('\n') + '\n');
+  return filePath;
+}
+
+test('sums input/output tokens across usage events in a session transcript', async () => {
+  const sessionId = 'sess-aaaa-1111';
+  writeTranscript(cwd, sessionId, [
+    { type: 'assistant', usage: { input_tokens: 100, output_tokens: 20 } },
+    { type: 'assistant', usage: { input_tokens: 50, output_tokens: 10 } },
+    { type: 'user', message: { content: 'no usage here' } },
+  ]);
+
+  const result = await usageFor(cwd, [sessionId]);
+  expect(result[sessionId]).toEqual({ inputTokens: 150, outputTokens: 30 });
+});
+
+test('maps a session with no transcript file to null', async () => {
+  const result = await usageFor(cwd, ['no-such-session']);
+  expect(result['no-such-session']).toBeNull();
+});
+
+test('batches multiple sessions in one call', async () => {
+  writeTranscript(cwd, 'sess-a', [{ usage: { input_tokens: 5, output_tokens: 1 } }]);
+  writeTranscript(cwd, 'sess-b', [{ usage: { input_tokens: 7, output_tokens: 2 } }]);
+
+  const result = await usageFor(cwd, ['sess-a', 'sess-b', 'sess-missing']);
+  expect(result).toEqual({
+    'sess-a': { inputTokens: 5, outputTokens: 1 },
+    'sess-b': { inputTokens: 7, outputTokens: 2 },
+    'sess-missing': null,
+  });
+});
+
+test('a repeat call against an unchanged file returns the same cached totals', async () => {
+  const sessionId = 'sess-cache';
+  writeTranscript(cwd, sessionId, [{ usage: { input_tokens: 10, output_tokens: 5 } }]);
+
+  const first = await usageFor(cwd, [sessionId]);
+  const second = await usageFor(cwd, [sessionId]);
+  expect(second[sessionId]).toEqual(first[sessionId]);
+  expect(second[sessionId]).toEqual({ inputTokens: 10, outputTokens: 5 });
+});
+
+test('a growing transcript is re-summed after the file mtime/size change', async () => {
+  const sessionId = 'sess-grow';
+  writeTranscript(cwd, sessionId, [{ usage: { input_tokens: 10, output_tokens: 5 } }]);
+  const before = await usageFor(cwd, [sessionId]);
+  expect(before[sessionId]).toEqual({ inputTokens: 10, outputTokens: 5 });
+
+  // Force a distinct mtime — some filesystems have coarse mtime resolution.
+  const filePath = transcriptPath(cwd, sessionId);
+  const future = new Date(Date.now() + 5000);
+  fs.appendFileSync(filePath, JSON.stringify({ usage: { input_tokens: 3, output_tokens: 1 } }) + '\n');
+  fs.utimesSync(filePath, future, future);
+
+  const after = await usageFor(cwd, [sessionId]);
+  expect(after[sessionId]).toEqual({ inputTokens: 13, outputTokens: 6 });
+});

package/src/main/__tests__/uniquePrdNumbers.test.cjs

@@ -0,0 +1,119 @@
+// PRD 832 — unique per-project PRD numbers + dependsOn eligibility.
+// User decision 2026-07-31: duplicate NN must be impossible; ordering is
+// expressed via dependsOn frontmatter, never via shared numbers.
+import { describe, it, expect } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const prdParser = require('../scheduler/prdParser.cjs');
+const { pickForProject } = require('../lib/schedulerBatch.cjs');
+
+function tmpdir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'sm-832-'));
+}
+
+const job = (slug, status, group, extra = {}) => ({
+  slug, status, parallelGroup: group, cwd: '/proj', ...extra,
+});
+
+describe('allocateParallelGroup extraFloor (PRD 832)', () => {
+  it('never allocates at or below the cross-dir max', async () => {
+    const dir = tmpdir();
+    // Bookkeeping dir itself is empty; another dir in the project already
+    // used numbers up to 830.
+    const nn = await prdParser.allocateParallelGroup(dir, { extraFloor: 830 });
+    expect(nn).toBe(831);
+    // And the high-water mark persists the raised floor for later calls.
+    const nn2 = await prdParser.allocateParallelGroup(dir);
+    expect(nn2).toBe(832);
+  });
+
+  it('local scan still wins when higher than extraFloor', async () => {
+    const dir = tmpdir();
+    fs.writeFileSync(path.join(dir, '900-existing.md'), '---\ntitle: x\n---\n# Goal\n');
+    const nn = await prdParser.allocateParallelGroup(dir, { extraFloor: 10 });
+    expect(nn).toBe(901);
+  });
+});
+
+describe('parsePrdRaw dependsOn (PRD 832)', () => {
+  it('parses bracket and comma forms, rejects junk', async () => {
+    const dir = tmpdir();
+    const fp = path.join(dir, '840-x.md');
+    fs.writeFileSync(fp, '---\ntitle: x\ncwd: /proj\ndependsOn: [833-epics-review-fixes, 834-guard]\n---\n# Goal\nbody\n');
+    const p = await prdParser.parsePrdRaw(fp);
+    expect(p.dependsOn).toEqual(['833-epics-review-fixes', '834-guard']);
+
+    const fp2 = path.join(dir, '841-y.md');
+    fs.writeFileSync(fp2, '---\ntitle: y\ncwd: /proj\ndependsOn: 833-a, ../evil/path, 834-b\n---\n# Goal\nbody\n');
+    const p2 = await prdParser.parsePrdRaw(fp2);
+    expect(p2.dependsOn).toEqual(['833-a', '834-b']);
+
+    const fp3 = path.join(dir, '842-z.md');
+    fs.writeFileSync(fp3, '---\ntitle: z\ncwd: /proj\n---\n# Goal\nbody\n');
+    const p3 = await prdParser.parsePrdRaw(fp3);
+    expect(p3.dependsOn).toEqual([]);
+  });
+});
+
+describe('pickForProject dependsOn eligibility (PRD 832)', () => {
+  it('holds a job while its dep row is pending/running; releases when completed', () => {
+    const dep = job('850-base', 'running', 850);
+    const dependent = job('851-next', 'pending', 851, { dependsOn: ['850-base'] });
+
+    // Dep running (tracked in queue rows, not runningSet) — not eligible.
+    let res = pickForProject([dep, dependent], new Set(), 3);
+    expect(res.batch.map((j) => j.slug)).not.toContain('851-next');
+
+    // Dep completed — eligible.
+    res = pickForProject([{ ...dep, status: 'completed' }, dependent], new Set(), 3);
+    expect(res.batch.map((j) => j.slug)).toContain('851-next');
+  });
+
+  it('a dep slug with NO queue row counts as done (retired to history)', () => {
+    const dependent = job('853-next', 'pending', 853, { dependsOn: ['852-archived-long-ago'] });
+    const res = pickForProject([dependent], new Set(), 3);
+    expect(res.batch.map((j) => j.slug)).toContain('853-next');
+  });
+
+  it('a FAILED dep holds the dependent with an explicit depends-gate reason', () => {
+    const dep = job('854-base', 'failed', 854);
+    const dependent = job('855-next', 'pending', 855, { dependsOn: ['854-base'] });
+    const res = pickForProject([dep, dependent], new Set(), 3);
+    expect(res.batch).toEqual([]);
+    expect(res.reason).toMatch(/depends-gate/);
+    expect(res.reason).toContain('855-next');
+    expect(res.reason).toContain('854-base');
+  });
+
+  it('legacy same-NN pending jobs keep their wave order untouched', () => {
+    const a = job('827-one', 'pending', 827);
+    const b = job('827-two', 'pending', 827);
+    const later = job('828-three', 'pending', 828);
+    const res = pickForProject([a, b, later], new Set(), 3);
+    expect(res.batch.map((j) => j.slug).sort()).toEqual(['827-one', '827-two']);
+  });
+});
+
+describe('reconcile retires archived-twin pending rows (post-832 cleanup)', () => {
+  it('drops a pending row whose PRD lives in prds-archived, keeps a normal invisible pending row', async () => {
+    const scheduler = require('../scheduler.cjs');
+    const root = tmpdir();
+    const opsDir = path.join(root, 'session-manager-operations', 'scheduler');
+    fs.mkdirSync(path.join(opsDir, 'prds'), { recursive: true });
+    fs.mkdirSync(path.join(opsDir, 'prds-archived'), { recursive: true });
+    fs.writeFileSync(path.join(opsDir, 'prds-archived', '833-landed-inline.md'), '---\ntitle: x\n---\n# Goal\n');
+
+    const state = {
+      jobs: [
+        job('833-landed-inline', 'pending', 833, { cwd: root }),
+        job('900-still-hidden', 'pending', 900, { cwd: root }),
+      ],
+    };
+    await scheduler.reconcile(state);
+    const slugs = state.jobs.map((j) => j.slug);
+    expect(slugs).not.toContain('833-landed-inline');
+    expect(slugs).toContain('900-still-hidden');
+  });
+});

package/src/main/config.cjs

@@ -152,6 +152,23 @@ function validateWrite(realAbs) {
       if (realAbs === promptSessionsSub || realAbs.startsWith(promptSessionsSub + path.sep)) {
         return;
       }
+      // Scheduler PRD sources (PRD 825 — per-project Epic PRD dirs under
+      // scheduler/epics/<id>/prds/, plus the legacy flat scheduler/prds/ and
+      // scheduler/state/ shards): narrowly scoped to
+      // session-manager-operations/scheduler/, this repo's existing
+      // per-project artifact-store convention (scheduler.cjs's remote.writePrd
+      // writes here via config.writeTextAtomic).
+      const schedulerSub = path.join(realRoot, 'session-manager-operations', 'scheduler');
+      if (realAbs === schedulerSub || realAbs.startsWith(schedulerSub + path.sep)) {
+        return;
+      }
+      // Project Brief persistence (PRD 837 — projectBrief.cjs's writeJson of
+      // brief.json): narrowly scoped to session-manager-operations/project-brief/,
+      // this repo's existing per-project artifact-store convention.
+      const briefSub = path.join(realRoot, 'session-manager-operations', 'project-brief');
+      if (realAbs === briefSub || realAbs.startsWith(briefSub + path.sep)) {
+        return;
+      }
     }
   }
   throw new Error(`Write outside allowed write boundaries: ${realAbs}`);

package/src/main/index.cjs

@@ -7,6 +7,7 @@ const os = require('node:os');
 const { schemas, validated } = require('./ipcSchemas.cjs');
 const { cleanChildEnv } = require('./lib/cleanEnv.cjs');
 const { terminateLosingInstance } = require('./lib/singleInstanceGuard.cjs');
+const { acquireSchedulerOwnership, releaseSchedulerOwnership } = require('./lib/instanceLock.cjs');
 const { manager: ptyManager, registerPtyHandlers } = require('./pty.cjs');
 const browserView = require('./browserView.cjs');
 const browserCapture = require('./browserCapture.cjs');
@@ -53,6 +54,7 @@ const { tryAcquireLock, releaseLock, DEFAULT_LOCK_PATH } = require('../../script
 const schedulerConfig = require('./lib/schedulerConfig.cjs');
 const memoryTool = require('./memoryTool.cjs');
 const { registerMemoryAggregateIpc } = require('./memoryAggregate.cjs');
+const { registerProjectBriefIpc } = require('./projectBrief.cjs');
 const agentMemory = require('./agentMemory.cjs');
 const git = require('./git.cjs');
 const filesIpc = require('./files.cjs');
@@ -769,6 +771,7 @@ registerHistoryDashboardHandlers();
 pluginInstall.registerPluginInstallHandlers();
 memoryTool.registerMemoryHandlers();
 registerMemoryAggregateIpc();
+registerProjectBriefIpc();
 agentMemory.registerAgentMemoryHandlers();
 git.register(ipcMain);
 filesIpc.registerFilesHandlers();
@@ -1090,12 +1093,26 @@ app.whenReady().then(async () => {
   webRemote.attachWindow(mainWindow);
   chatRunner.attachWindow(mainWindow);
   attachDocEditWindow(mainWindow);
-  scheduler.init().catch((e) => {
-    logs.writeLine({ scope: 'scheduler', level: 'error', message: 'init failed', meta: { error: e?.message } });
-  });
-  adminHttp.start().catch((e) => {
-    logs.writeLine({ scope: 'admin-server', level: 'error', message: 'init failed', meta: { error: e?.message } });
-  });
+  // Scheduler ownership (PRD 834): exactly one instance machine-wide runs
+  // scheduler mutation (boot reconciliation, ticking, sweep, supervisor) and
+  // the admin API. Electron's own single-instance lock is keyed by userData
+  // identity, which a dev/e2e/Playwright launch bypasses — live incident
+  // 2026-07-31: a secondary instance's boot reconciliation SIGTERM'd the
+  // owner's running job and overwrote admin-api.json. Losing instances run
+  // scheduler-PASSIVE: read IPC still works (handlers registered above),
+  // nothing mutates.
+  const ownership = acquireSchedulerOwnership();
+  if (ownership.owner) {
+    scheduler.init().catch((e) => {
+      logs.writeLine({ scope: 'scheduler', level: 'error', message: 'init failed', meta: { error: e?.message } });
+    });
+    adminHttp.start().catch((e) => {
+      logs.writeLine({ scope: 'admin-server', level: 'error', message: 'init failed', meta: { error: e?.message } });
+    });
+  } else {
+    console.log(`[main] scheduler ownership held by pid ${ownership.holderPid} — running scheduler-passive (no reconciliation, no admin server)`);
+    logs.writeLine({ scope: 'scheduler', level: 'info', message: 'scheduler-passive: ownership held by another instance', meta: { holderPid: ownership.holderPid } });
+  }
   browserAgentServer.start().catch((e) => {
     logs.writeLine({ scope: 'browser-agent-server', level: 'error', message: 'init failed', meta: { error: e?.message } });
   });
@@ -1199,6 +1216,7 @@ app.on('activate', () => {
 });
 
 app.on('before-quit', () => {
+  releaseSchedulerOwnership();
   supervisor.stopSupervisor();
   ptyManager.killAll();
   configMgr.closeAllWatchers();

package/src/main/ipcSchemas.cjs

@@ -20,6 +20,10 @@ const ptySpawn = z.object({
 
 const ptyTabId = z.object({ tabId: z.string().min(1).max(128) });
 
+// PRD 833 C1: Epics-workspace reconcile — which of these session keys still
+// have a live PTY? Bounded so the renderer can't ask about unbounded lists.
+const ptyAlive = z.object({ tabIds: z.array(z.string().min(1).max(128)).max(500) });
+
 // v2 mobile: subscribe to a session's live state + summary. cwd is needed to
 // locate the transcript JSONL (transcriptPath); validated against home-dir boundary
 // in webRemote before any fs access.
@@ -168,6 +172,14 @@ const transcriptPath = z.object({
   sessionUuid: z.string().regex(SESSION_UUID_RE),
 });
 
+// Batched token-usage lookup for the Epics workspace (one call per visible
+// set of Epics rather than a per-row IPC round trip). Bounded array size —
+// mirrors ptyAlive's cap for the same reason (renderer can't ask unbounded).
+const transcriptUsageFor = z.object({
+  cwd: z.string().min(1).max(4096),
+  sessionIds: z.array(z.string().regex(SESSION_UUID_RE)).max(500),
+});
+
 // ──────────────────────────────────────────── Config
 const configPath = z.object({ path: z.string().min(1).max(4096) });
 
@@ -266,7 +278,12 @@ const schedulerCreatePrd = z.object({
   implementationNotes: z.string().min(1).max(20000),
   outOfScope: z.array(z.string().min(1).max(2000)).max(100).optional(),
   slug: z.string().min(1).max(60).regex(PRD_CREATE_SLUG_RE).optional(),
+  // DEPRECATED (PRD 832): accepted for wire-compat but ignored — numbers are
+  // strictly unique per project; use dependsOn for ordering.
   parallelGroup: z.number().int().min(1).max(999999).optional(),
+  // 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
@@ -395,6 +412,20 @@ const memoryAggregate = z.object({
   refresh: z.boolean().optional(),
 }).strict();
 
+// ──────────────────────────────────────────── Project Brief (PRD 837)
+// cwd is validated for real via config.cjs's validatePath (allowedRoots =
+// home dir) at first fs access in projectBrief.cjs — this schema only bounds
+// the wire shape.
+const PROJECT_BRIEF_BLOCK = z.enum(['what', 'conventions']);
+const projectBriefCwd = z.object({
+  cwd: z.string().min(1).max(4096),
+}).strict();
+const projectBriefSetPin = z.object({
+  cwd: z.string().min(1).max(4096),
+  block: PROJECT_BRIEF_BLOCK,
+  pinned: z.boolean(),
+}).strict();
+
 // ──────────────────────────────────────────── Per-subagent memory
 // Distinct from the workspace-scoped Memory tool: agentMemory is keyed by
 // subagent name (the .md filename in ~/.claude/agents/, e.g. "code-reviewer"),
@@ -726,6 +757,7 @@ module.exports = {
     webRemoteAuditTail,
     ptySpawn,
     ptyTabId,
+    ptyAlive,
     ptyWrite,
     ptyResize,
     sessionSubscribe,
@@ -745,6 +777,7 @@ module.exports = {
     transcriptSubscribe,
     transcriptTabId,
     transcriptPath,
+    transcriptUsageFor,
     configPath,
     configWriteJson,
     configWriteText,
@@ -782,6 +815,8 @@ module.exports = {
     memoryCreate,
     memoryAggregate,
     memoryStale,
+    projectBriefCwd,
+    projectBriefSetPin,
     agentMemoryList,
     agentMemoryGet,
     agentMemorySet,

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

@@ -0,0 +1,87 @@
+// PRD 834 — machine-wide scheduler-ownership lock. Secondary instances must
+// go scheduler-passive instead of running boot reconciliation / admin server
+// against the owner's queue state (live incident 2026-07-31).
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const {
+  acquireSchedulerOwnership,
+  releaseSchedulerOwnership,
+  pidAlive,
+  lockPath,
+} = require('../instanceLock.cjs');
+
+let dir;
+
+beforeEach(() => {
+  dir = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-instance-lock-'));
+  process.env.SM_SCHEDULER_LOCK_PATH = path.join(dir, 'scheduler-owner.lock');
+});
+
+afterEach(() => {
+  delete process.env.SM_SCHEDULER_LOCK_PATH;
+  fs.rmSync(dir, { recursive: true, force: true });
+});
+
+describe('instanceLock (PRD 834)', () => {
+  it('first acquirer becomes owner and writes its pid', () => {
+    const res = acquireSchedulerOwnership();
+    expect(res.owner).toBe(true);
+    const onDisk = JSON.parse(fs.readFileSync(lockPath(), 'utf8'));
+    expect(onDisk.pid).toBe(process.pid);
+  });
+
+  it('a live foreign holder makes acquisition passive with the holder pid reported', () => {
+    // Use our own live pid as the "foreign" holder — pidAlive(process.pid) is
+    // true, and acquire treats pid !== process.pid as foreign, so fake one by
+    // writing pid 1 (init — always alive, never ours).
+    fs.mkdirSync(path.dirname(lockPath()), { recursive: true });
+    fs.writeFileSync(lockPath(), JSON.stringify({ pid: 1, startedAt: 'x' }));
+    const res = acquireSchedulerOwnership();
+    expect(res.owner).toBe(false);
+    expect(res.holderPid).toBe(1);
+    // The holder's lock is untouched.
+    expect(JSON.parse(fs.readFileSync(lockPath(), 'utf8')).pid).toBe(1);
+  });
+
+  it('a stale lock (dead pid) is broken and ownership taken', () => {
+    // Find a pid that is certainly dead: spawn nothing — use a huge pid
+    // beyond pid_max defaults.
+    fs.mkdirSync(path.dirname(lockPath()), { recursive: true });
+    fs.writeFileSync(lockPath(), JSON.stringify({ pid: 2 ** 30, startedAt: 'x' }));
+    const res = acquireSchedulerOwnership();
+    expect(res.owner).toBe(true);
+    expect(JSON.parse(fs.readFileSync(lockPath(), 'utf8')).pid).toBe(process.pid);
+  });
+
+  it('re-acquiring our own lock stays owner (idempotent across re-init)', () => {
+    expect(acquireSchedulerOwnership().owner).toBe(true);
+    expect(acquireSchedulerOwnership().owner).toBe(true);
+  });
+
+  it('release removes only our own lock', () => {
+    acquireSchedulerOwnership();
+    releaseSchedulerOwnership();
+    expect(fs.existsSync(lockPath())).toBe(false);
+    // A foreign lock is never removed by release.
+    fs.writeFileSync(lockPath(), JSON.stringify({ pid: 1, startedAt: 'x' }));
+    releaseSchedulerOwnership();
+    expect(fs.existsSync(lockPath())).toBe(true);
+  });
+
+  it('a corrupt lock file is treated as stale, not fatal', () => {
+    fs.mkdirSync(path.dirname(lockPath()), { recursive: true });
+    fs.writeFileSync(lockPath(), 'not json {');
+    const res = acquireSchedulerOwnership();
+    expect(res.owner).toBe(true);
+  });
+
+  it('pidAlive: own pid alive, absurd pid dead', () => {
+    expect(pidAlive(process.pid)).toBe(true);
+    expect(pidAlive(2 ** 30)).toBe(false);
+    expect(pidAlive(-5)).toBe(false);
+    expect(pidAlive(0)).toBe(false);
+  });
+});

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

@@ -0,0 +1,142 @@
+// projectBriefCore.cjs — pure logic for the Brief backend (PRD 837).
+// vitest globals (test/beforeEach/afterEach) — same convention as the other .cjs tests.
+const assert = require('node:assert/strict');
+const {
+  computeDrift,
+  buildSources,
+  buildSynthesisPrompt,
+  validateBriefShape,
+  applyPinEnforcement,
+  buildPersistedBrief,
+  computeSetPin,
+} = require('../projectBriefCore.cjs');
+
+test('computeDrift: true only when mtime strictly newer than synthesizedAt', () => {
+  assert.equal(computeDrift(200, 100), true);
+  assert.equal(computeDrift(100, 200), false);
+  assert.equal(computeDrift(100, 100), false);
+  assert.equal(computeDrift(null, 100), false);
+  assert.equal(computeDrift(200, null), false);
+});
+
+test('buildSources: omits null sources, computes drift per source', () => {
+  const synthesizedAt = new Date(1_000_000).toISOString();
+  const sources = buildSources({
+    synthesizedAt,
+    claudeMd: { detail: '40 lines', mtimeMs: 500_000 },
+    epics: { detail: '2 active · 1 archived', mtimeMs: 2_000_000 },
+    sessions: null,
+    git: { detail: '12 commits', mtimeMs: 900_000 },
+  });
+  assert.equal(sources.length, 3);
+  const byLabel = Object.fromEntries(sources.map((s) => [s.label, s]));
+  assert.equal(byLabel['CLAUDE.md'].drift, false);
+  assert.equal(byLabel['Epics'].drift, true);
+  assert.equal(byLabel['Git'].drift, false);
+  assert.equal(byLabel['Sessions'], undefined);
+});
+
+test('buildSources: no synthesizedAt yet means nothing drifts', () => {
+  const sources = buildSources({
+    synthesizedAt: null,
+    claudeMd: { detail: '1 line', mtimeMs: 999 },
+    epics: null,
+    sessions: null,
+    git: null,
+  });
+  assert.equal(sources[0].drift, false);
+});
+
+test('buildSynthesisPrompt includes CLAUDE.md, epics, git log, tree, and pinned block instruction', () => {
+  const prompt = buildSynthesisPrompt({
+    claudeMdText: '# Project X',
+    epics: [{ status: 'active', tag: 'feature', goalText: 'Ship the thing' }],
+    gitLogLines: ['abc123 fix bug'],
+    srcTree: 'src/\n  main/\n  renderer/',
+    pinnedBlocks: { conventions: ['Never use shell:true'] },
+  });
+  assert.match(prompt, /# Project X/);
+  assert.match(prompt, /Ship the thing/);
+  assert.match(prompt, /abc123 fix bug/);
+  assert.match(prompt, /src\/\n  main\//);
+  assert.match(prompt, /PINNED BLOCK "conventions"/);
+  assert.match(prompt, /Never use shell:true/);
+  assert.doesNotMatch(prompt, /PINNED BLOCK "what"/);
+});
+
+test('validateBriefShape: accepts a well-formed object, rejects malformed ones', () => {
+  const good = { purpose: 'x', what: [], areas: [], scope: [], conventions: [] };
+  assert.deepEqual(validateBriefShape(good), { ok: true, error: null });
+  assert.equal(validateBriefShape(null).ok, false);
+  assert.equal(validateBriefShape({ ...good, purpose: '' }).ok, false);
+  assert.equal(validateBriefShape({ ...good, what: 'not an array' }).ok, false);
+  assert.equal(validateBriefShape({ ...good, areas: undefined }).ok, false);
+});
+
+test('applyPinEnforcement: overwrites a pinned block with the frozen copy, carries pins/pinned forward', () => {
+  const raw = { purpose: 'p', what: ['fresh what'], areas: [], scope: [], conventions: ['fresh conventions'] };
+  const priorPins = { what: false, conventions: true };
+  const priorPinned = { what: null, conventions: ['frozen conventions'] };
+  const merged = applyPinEnforcement(raw, priorPins, priorPinned);
+  assert.deepEqual(merged.what, ['fresh what']);
+  assert.deepEqual(merged.conventions, ['frozen conventions']);
+  assert.deepEqual(merged.pins, priorPins);
+  assert.deepEqual(merged.pinned, priorPinned);
+});
+
+test('applyPinEnforcement: unpinned brief passes model output through untouched', () => {
+  const raw = { purpose: 'p', what: ['fresh'], areas: [], scope: [], conventions: ['fresh'] };
+  const merged = applyPinEnforcement(raw, null, null);
+  assert.deepEqual(merged.what, ['fresh']);
+  assert.deepEqual(merged.conventions, ['fresh']);
+  assert.deepEqual(merged.pins, { what: false, conventions: false });
+});
+
+test('buildPersistedBrief stamps version/synthesizedAt/model and enforces pins', () => {
+  const raw = { purpose: 'p', what: ['fresh'], areas: [{ name: 'a', files: 1, note: '', epic: null, heat: 0.1 }], scope: [], conventions: ['fresh'] };
+  const persisted = buildPersistedBrief({
+    rawBrief: raw,
+    priorPins: { what: true, conventions: false },
+    priorPinned: { what: ['frozen what'], conventions: null },
+    model: 'claude-sonnet-5',
+    nowIso: '2026-07-31T00:00:00.000Z',
+  });
+  assert.equal(persisted.version, 1);
+  assert.equal(persisted.synthesizedAt, '2026-07-31T00:00:00.000Z');
+  assert.equal(persisted.model, 'claude-sonnet-5');
+  assert.deepEqual(persisted.what, ['frozen what']);
+  assert.deepEqual(persisted.conventions, ['fresh']);
+  assert.deepEqual(persisted.areas, raw.areas);
+});
+
+test('computeSetPin: errors when there is no brief yet', () => {
+  const res = computeSetPin(null, 'what', true);
+  assert.equal(res.ok, false);
+});
+
+test('computeSetPin: errors on an unpinnable block', () => {
+  const brief = { purpose: 'p', what: [], areas: [], scope: [], conventions: [], pins: {}, pinned: {} };
+  const res = computeSetPin(brief, 'areas', true);
+  assert.equal(res.ok, false);
+});
+
+test('computeSetPin: pinning freezes current block content, unpinning clears it', () => {
+  const brief = {
+    purpose: 'p',
+    what: ['a', 'b'],
+    areas: [],
+    scope: [],
+    conventions: ['c1'],
+    pins: { what: false, conventions: false },
+    pinned: { what: null, conventions: null },
+  };
+  const pinned = computeSetPin(brief, 'what', true);
+  assert.equal(pinned.ok, true);
+  assert.equal(pinned.brief.pins.what, true);
+  assert.deepEqual(pinned.brief.pinned.what, ['a', 'b']);
+
+  const unpinned = computeSetPin(pinned.brief, 'what', false);
+  assert.equal(unpinned.ok, true);
+  assert.equal(unpinned.brief.pins.what, false);
+  assert.equal(unpinned.brief.pinned.what, null);
+});

package/src/main/lib/epicMint.cjs

@@ -141,4 +141,4 @@ function appendPrdCreatedEvent(cwd, epicId, prdSlug, text) {
   return true;
 }
 
-module.exports = { ensureEpic, appendPrdCreatedEvent, activeIndexPath };
+module.exports = { ensureEpic, appendPrdCreatedEvent, activeIndexPath, readActiveIndex };