claude-code-session-manager 0.95.0 → 0.97.0

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

@@ -0,0 +1,110 @@
+/**
+ * schedulerStateSidecarRestore.test.cjs — covers PRD 1392: scheduler-state.json
+ * previously left lastPollOk, lastFailureKind, backoffNextAt, cachedUtilization and
+ * cachedBindingWindowName memory-only, so a fresh boot showed misleading footer/KPI
+ * placeholders (a healthy poller reading "failed", a still-rate-limited state
+ * un-showable, utilization stuck at "—") until the next post-boot billing poll
+ * overwrote them. Proves loadSchedulerState() restores all five from disk instead of
+ * leaving the hardcoded defaults (false / null / null / null / null) in place.
+ *
+ * scheduler.cjs is a plain CJS require (like rateLimitPollerStreak.test.cjs's), so its
+ * module-level `let`s are a singleton for this test file's process — the first test
+ * below captures the pre-load snapshot itself (the hardcoded defaults) rather than
+ * assuming a fresh module per test, so the proof doesn't depend on test ordering.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/schedulerStateSidecarRestore.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeEach } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const { loadSchedulerState, persistSchedulerState, getSchedulerStateSnapshot } = require('../scheduler.cjs');
+const schedulerPaths = require('../lib/schedulerPaths.cjs');
+
+function writeSidecar(data) {
+  fs.mkdirSync(path.dirname(schedulerPaths.schedulerStatePath()), { recursive: true });
+  fs.writeFileSync(schedulerPaths.schedulerStatePath(), JSON.stringify(data));
+}
+
+beforeEach(() => {
+  try { fs.unlinkSync(schedulerPaths.schedulerStatePath()); } catch { /* no sidecar yet */ }
+});
+
+test('loadSchedulerState restores lastPollOk/lastFailureKind/backoffNextAt/cachedUtilization/cachedBindingWindowName from the sidecar, not the hardcoded defaults', () => {
+  // Before a restore, the module starts (or was left, by whatever ran before this test
+  // in-process) at whatever it was — capture it so the assertion below is a genuine
+  // "changed to match the file" proof, not an assumption about fresh-module defaults.
+  const before = getSchedulerStateSnapshot();
+
+  const written = {
+    version: 1,
+    lastPollOk: true,
+    lastFailureKind: 'meter_rate_limited',
+    backoffNextAt: 1_726_000_000_000,
+    cachedUtilization: 42,
+    cachedBindingWindowName: 'five_hour',
+  };
+  writeSidecar(written);
+
+  // Simulate a restart: a fresh process starts from the hardcoded module defaults
+  // (false / null / null / null / null) until loadSchedulerState() runs.
+  loadSchedulerState();
+
+  const after = getSchedulerStateSnapshot();
+  expect(after).toEqual({
+    lastPollOk: true,
+    lastFailureKind: 'meter_rate_limited',
+    backoffNextAt: 1_726_000_000_000,
+    cachedUtilization: 42,
+    cachedBindingWindowName: 'five_hour',
+  });
+  // The restore must have actually changed something relative to the pre-load
+  // snapshot — proves this run exercised the restore path, not a no-op.
+  expect(after).not.toEqual(before);
+});
+
+test('persistSchedulerState writes the same five fields back out, round-tripping through the sidecar', () => {
+  writeSidecar({
+    version: 1,
+    lastPollOk: false,
+    lastFailureKind: 'auth',
+    backoffNextAt: 1_726_100_000_000,
+    cachedUtilization: 87.5,
+    cachedBindingWindowName: 'weekly_all',
+  });
+  loadSchedulerState();
+
+  persistSchedulerState();
+
+  const onDisk = JSON.parse(fs.readFileSync(schedulerPaths.schedulerStatePath(), 'utf8'));
+  expect(onDisk.lastPollOk).toBe(false);
+  expect(onDisk.lastFailureKind).toBe('auth');
+  expect(onDisk.backoffNextAt).toBe(1_726_100_000_000);
+  expect(onDisk.cachedUtilization).toBe(87.5);
+  expect(onDisk.cachedBindingWindowName).toBe('weekly_all');
+});
+
+test('loadSchedulerState against a sidecar missing the five fields leaves the in-memory values unchanged (pre-PRD-1392 file)', () => {
+  // Establish a known non-default in-memory state first.
+  writeSidecar({
+    version: 1,
+    lastPollOk: true,
+    lastFailureKind: 'transient',
+    backoffNextAt: 5000,
+    cachedUtilization: 10,
+    cachedBindingWindowName: 'seven_day',
+  });
+  loadSchedulerState();
+  const established = getSchedulerStateSnapshot();
+
+  // A sidecar written before PRD 1392 (or first-boot with only the older fields) has
+  // none of the five new keys — loadSchedulerState's per-field `typeof` guards must
+  // leave whatever was already in memory alone, not stomp it back to a hardcoded default.
+  writeSidecar({ version: 1, lastPollAt: 123 });
+  loadSchedulerState();
+
+  expect(getSchedulerStateSnapshot()).toEqual(established);
+});

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

@@ -54,7 +54,7 @@ function silentLogger() {
   return { log: () => {}, warn: () => {} };
 }
 
-const ALL_PERSONAS = ['architect', 'dev-lead', 'project-home-builder'];
+const ALL_PERSONAS = ['architect', 'dev-lead', 'project-home-builder', 'validator'];
 
 test('fresh seed writes every persona file', async () => {
   await seedAgentPersonas({ logger: silentLogger() });
@@ -156,6 +156,24 @@ test('the bundled project-home-builder persona contains no session-manager-repo
   }
 });
 
+test('seeded dev-lead persona pins an executor-tier model', () => {
+  const { splitFrontmatter } = require('../lib/prdFrontmatter.cjs');
+  const raw = fs.readFileSync(path.join(__dirname, '..', '..', 'seed', 'agents', 'dev-lead.md'), 'utf8');
+  const { fm } = splitFrontmatter(raw);
+  expect(fm.model).toBe('sonnet');
+});
+
+test('seeded dev-lead body fits AGENT_BODY_CHAR_CAP and carries the run contract', () => {
+  const { splitFrontmatter } = require('../lib/prdFrontmatter.cjs');
+  const { AGENT_BODY_CHAR_CAP } = require('../lib/agentModelResolve.cjs');
+  const raw = fs.readFileSync(path.join(__dirname, '..', '..', 'seed', 'agents', 'dev-lead.md'), 'utf8');
+  const { body } = splitFrontmatter(raw);
+  const trimmed = body.trim();
+  expect(trimmed.length).toBeLessThan(AGENT_BODY_CHAR_CAP);
+  expect(trimmed).toContain('## Run contract');
+  expect(trimmed).toContain('SCHEDULER_VERDICT: PASS');
+});
+
 test('SM_SEED_AGENT_PERSONAS_DISABLE=1 short-circuits', async () => {
   process.env.SM_SEED_AGENT_PERSONAS_DISABLE = '1';
 

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

@@ -0,0 +1,116 @@
+/**
+ * seedValidatorPersona.test.cjs — covers the `validator` persona's delivery
+ * through seedAgentPersonas.cjs's existing "names not yet in `seeded`" path.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/seedValidatorPersona.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');
+
+let tmpHome;
+let realHome;
+let seedAgentPersonas;
+
+// config.cjs bakes os.homedir() into top-level consts at first require
+// (allowedRoots/WRITE_PREFIXES, used by writeJsonSync) — must be purged
+// alongside seedAgentPersonas.cjs so each test's tmpHome takes effect.
+const MODULES_TO_RELOAD = ['../seedAgentPersonas.cjs', '../config.cjs'];
+
+function purgeRequireCache() {
+  for (const m of MODULES_TO_RELOAD) {
+    try { delete require.cache[require.resolve(m)]; } catch { /* not loaded yet */ }
+  }
+}
+
+beforeEach(() => {
+  realHome = process.env.HOME;
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'seed-validator-persona-test-'));
+  process.env.HOME = tmpHome;
+  delete process.env.SM_SEED_AGENT_PERSONAS_DISABLE;
+  purgeRequireCache();
+  ({ seedAgentPersonas } = require('../seedAgentPersonas.cjs'));
+});
+
+afterEach(() => {
+  process.env.HOME = realHome;
+  delete process.env.SM_SEED_AGENT_PERSONAS_DISABLE;
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+  purgeRequireCache();
+});
+
+function agentsDir() {
+  return path.join(tmpHome, '.claude', 'agents');
+}
+
+function markerPath() {
+  return path.join(tmpHome, '.claude', 'session-manager', '.agent-personas-seeded');
+}
+
+function silentLogger() {
+  return { log: () => {}, warn: () => {} };
+}
+
+const ALL_PERSONAS = ['architect', 'dev-lead', 'project-home-builder', 'validator'];
+const seedSrc = (name) => path.join(__dirname, '..', '..', 'seed', 'agents', `${name}.md`);
+
+test('a fresh homedir gets all four persona files', async () => {
+  await seedAgentPersonas({ logger: silentLogger() });
+
+  for (const name of ALL_PERSONAS) {
+    const dest = path.join(agentsDir(), `${name}.md`);
+    expect(fs.existsSync(dest)).toBe(true);
+    expect(fs.readFileSync(dest, 'utf8')).toBe(fs.readFileSync(seedSrc(name), 'utf8'));
+  }
+
+  const marker = JSON.parse(fs.readFileSync(markerPath(), 'utf8'));
+  expect(marker.seeded.sort()).toEqual([...ALL_PERSONAS].sort());
+});
+
+test('a homedir whose marker already lists the first three receives validator.md, and the other three files are byte-identical before and after', async () => {
+  const mPath = markerPath();
+  fs.mkdirSync(path.dirname(mPath), { recursive: true });
+  fs.writeFileSync(
+    mPath,
+    JSON.stringify({ seeded: ['architect', 'dev-lead', 'project-home-builder'], attempts: 0, ts: '2026-01-01T00:00:00.000Z' })
+  );
+  fs.mkdirSync(agentsDir(), { recursive: true });
+  const preExisting = {};
+  for (const name of ['architect', 'dev-lead', 'project-home-builder']) {
+    const content = `existing ${name} content\n`;
+    fs.writeFileSync(path.join(agentsDir(), `${name}.md`), content);
+    preExisting[name] = content;
+  }
+
+  expect(fs.existsSync(path.join(agentsDir(), 'validator.md'))).toBe(false);
+
+  await seedAgentPersonas({ logger: silentLogger() });
+
+  expect(fs.readFileSync(path.join(agentsDir(), 'validator.md'), 'utf8')).toBe(fs.readFileSync(seedSrc('validator'), 'utf8'));
+
+  for (const name of ['architect', 'dev-lead', 'project-home-builder']) {
+    expect(fs.readFileSync(path.join(agentsDir(), `${name}.md`), 'utf8')).toBe(preExisting[name]);
+  }
+
+  const marker = JSON.parse(fs.readFileSync(mPath, 'utf8'));
+  expect(marker.seeded.sort()).toEqual([...ALL_PERSONAS].sort());
+});
+
+test('the seeded validator body is under AGENT_BODY_CHAR_CAP and contains both required sentinel lines', () => {
+  const { AGENT_BODY_CHAR_CAP } = require('../lib/agentModelResolve.cjs');
+  const { splitFrontmatter } = require('../lib/prdFrontmatter.cjs');
+  const raw = fs.readFileSync(seedSrc('validator'), 'utf8');
+  const { body } = splitFrontmatter(raw);
+  const trimmed = body.trim();
+
+  expect(trimmed.length).toBeLessThan(AGENT_BODY_CHAR_CAP);
+  expect(trimmed).toContain('VALIDATION: <slug> VERIFIED');
+  expect(trimmed).toContain('SCHEDULER_VERDICT: PASS');
+  expect(trimmed).not.toContain('Do not touch:');
+  expect(trimmed).not.toContain('Report explicitly:');
+  expect(trimmed.endsWith('report them.')).toBe(true);
+});

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

@@ -78,8 +78,8 @@ function freshClient(home, profileOverrides) {
   // Explicit opt-in: this suite deliberately exercises telemetryClient's real
   // queue/sent-file I/O, so it must override the test-environment no-op guard
   // by pointing the spool at this test's own isolated tmp dir (never a real
-  // user's ~/.config/session-manager).
-  process.env.SM_TELEMETRY_SPOOL = path.join(home, '.config', 'session-manager');
+  // user's ~/.claude/session-manager).
+  process.env.SM_TELEMETRY_SPOOL = path.join(home, '.claude', 'session-manager');
   for (const p of ['../lib/telemetryClient.cjs', '../config.cjs', '../lib/telemetrySettings.cjs', '../lib/machineProfile.cjs']) {
     const resolved = require.resolve(p);
     delete require.cache[resolved];

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

@@ -348,7 +348,7 @@ function freshClient(home, profileOverrides) {
   process.env.HOME = home;
   // Explicit opt-in: overrides the test-environment no-op guard so this
   // suite's real telemetryClient calls actually persist into an isolated dir.
-  process.env.SM_TELEMETRY_SPOOL = path.join(home, '.config', 'session-manager');
+  process.env.SM_TELEMETRY_SPOOL = path.join(home, '.claude', 'session-manager');
   for (const p of HOME_DEPENDENT_MODULES) {
     const resolved = require.resolve(p);
     delete require.cache[resolved];
@@ -695,7 +695,7 @@ test('records queued, a 503 mid-drain, then a fresh client flushing successfully
 
   expect(stubServer.state.errors.length).toBe(before); // nothing landed during the failure
 
-  const wmPath = path.join(home, '.config', 'session-manager', 'telemetry-watermarks.json');
+  const wmPath = path.join(home, '.claude', 'session-manager', 'telemetry-watermarks.json');
   const wmAfterFailure = JSON.parse(await fsp.readFile(wmPath, 'utf8'));
   const entryAfterFailure = Object.values(wmAfterFailure).find((e) => e && typeof e === 'object' && 'bytesConfirmed' in e);
   expect(entryAfterFailure.bytesConfirmed).toBe(0); // bytesConfirmed frozen during the failed phase

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

@@ -88,6 +88,7 @@ afterEach(() => {
   process.env.HOME = realHome;
   vi.unstubAllGlobals();
   vi.restoreAllMocks();
+  vi.useRealTimers();
   purgeRequireCache();
   // maxRetries: a fire-and-forget cache write inside usage.cjs can land in .claude/ mid-rm
   // (ENOTEMPTY) when the machine is loaded; this is cleanup robustness, not a test retry.
@@ -112,6 +113,15 @@ test('two concurrent fetchUsage() calls produce exactly one HTTP fetch', async (
 });
 
 test('an ok result resets the shared circuit streak built up by prior failures', async () => {
+  // The breaker's open->half_open transition (usageCircuit.cjs's state())
+  // compares real Date.now() against a jittered 15-30s backoff deadline. On
+  // a loaded machine, real wall-clock time can drift far enough between the
+  // 3rd failure and the assertions below for that deadline to pass, flipping
+  // 'open' to 'half_open' out from under this test. Freeze time so the
+  // open/closed assertions are decided by call sequence, not the real clock.
+  vi.useFakeTimers();
+  vi.setSystemTime(Date.now());
+
   const usage = require('../usage.cjs');
   const circuit = usage.__usageCircuitForTest;
 

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

@@ -0,0 +1,84 @@
+/**
+ * validationSentinels.test.cjs — unit tests for parseValidationSentinels
+ * (PRD 1407): a plan-level validator job ends its run with one
+ * `VALIDATION: <slug> VERIFIED` or `VALIDATION: <slug> REFUTED — <reason>`
+ * line per PRD; this module extracts those lines from the job's result text.
+ *
+ * Run: timeout 300 npx vitest run src/main/__tests__/validationSentinels.test.cjs
+ */
+
+'use strict';
+
+import { test, expect } from 'vitest';
+const { parseValidationSentinels } = require('../lib/validationSentinels.cjs');
+
+test('parses a VERIFIED line with no reason', () => {
+  expect(parseValidationSentinels('VALIDATION: 123-foo VERIFIED')).toEqual([
+    { slug: '123-foo', verdict: 'verified', reason: '' },
+  ]);
+});
+
+test('parses a REFUTED line with an em-dash reason', () => {
+  expect(parseValidationSentinels('VALIDATION: 123-foo REFUTED — missing test coverage')).toEqual([
+    { slug: '123-foo', verdict: 'refuted', reason: 'missing test coverage' },
+  ]);
+});
+
+test('parses a REFUTED line with an en-dash reason', () => {
+  expect(parseValidationSentinels('VALIDATION: 123-foo REFUTED – bad wiring')).toEqual([
+    { slug: '123-foo', verdict: 'refuted', reason: 'bad wiring' },
+  ]);
+});
+
+test('parses a REFUTED line with a hyphen reason', () => {
+  expect(parseValidationSentinels('VALIDATION: 123-foo REFUTED - wrong file touched')).toEqual([
+    { slug: '123-foo', verdict: 'refuted', reason: 'wrong file touched' },
+  ]);
+});
+
+test('parses a REFUTED line with no reason', () => {
+  expect(parseValidationSentinels('VALIDATION: 123-foo REFUTED')).toEqual([
+    { slug: '123-foo', verdict: 'refuted', reason: '' },
+  ]);
+});
+
+test('ignores lowercase verified/refuted', () => {
+  expect(parseValidationSentinels('VALIDATION: 123-foo verified')).toEqual([]);
+  expect(parseValidationSentinels('VALIDATION: 123-foo refuted')).toEqual([]);
+});
+
+test('ignores every other line in a multi-line transcript', () => {
+  const text = [
+    'Some preamble text',
+    'Running gate...',
+    'VALIDATION: 111-alpha VERIFIED',
+    'random noise mentioning VALIDATION: not-a-real-line',
+    'VALIDATION: 222-beta REFUTED — the fix was incomplete',
+    'trailing notes',
+  ].join('\n');
+
+  expect(parseValidationSentinels(text)).toEqual([
+    { slug: '111-alpha', verdict: 'verified', reason: '' },
+    { slug: '222-beta', verdict: 'refuted', reason: 'the fix was incomplete' },
+  ]);
+});
+
+test('last line per slug wins, order of first appearance kept', () => {
+  const text = [
+    'VALIDATION: 111-alpha VERIFIED',
+    'VALIDATION: 222-beta REFUTED — first reason',
+    'VALIDATION: 111-alpha REFUTED — actually broken',
+    'VALIDATION: 222-beta VERIFIED',
+  ].join('\n');
+
+  expect(parseValidationSentinels(text)).toEqual([
+    { slug: '111-alpha', verdict: 'refuted', reason: 'actually broken' },
+    { slug: '222-beta', verdict: 'verified', reason: '' },
+  ]);
+});
+
+test('returns [] for null, undefined, and empty input', () => {
+  expect(parseValidationSentinels(null)).toEqual([]);
+  expect(parseValidationSentinels(undefined)).toEqual([]);
+  expect(parseValidationSentinels('')).toEqual([]);
+});

package/src/main/build-info.json

@@ -1,8 +1,8 @@
 {
-  "version": "0.95.0",
-  "gitSha": "42f7779080772b1b8432b6287aff06c52b9f0f90",
-  "gitShortSha": "42f77790",
+  "version": "0.97.0",
+  "gitSha": "c68cf49f55d9fda43114a70f1fb21142979cce11",
+  "gitShortSha": "c68cf49f",
   "gitBranch": "HEAD",
-  "builtAt": "2026-09-21T22:01:57.972Z",
+  "builtAt": "2026-09-25T03:03:56.111Z",
   "dirty": false
 }

package/src/main/config.cjs

@@ -19,7 +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, opsPath } = require('./lib/opsOwnership.cjs');
+const { assertOpsWrite, opsPath, OWNERS } = require('./lib/opsOwnership.cjs');
 const chokidar = require('chokidar');
 const logs = require('./logs.cjs');
 const { sendIfAlive } = require('./lib/sendToRenderer.cjs');
@@ -113,7 +113,6 @@ const WRITE_PREFIXES = [
   path.join(os.homedir(), '.claude'),
   path.join(os.homedir(), '.claude.json'), // global MCP servers config
   path.join(os.homedir(), '.config', 'claude-code'),
-  path.join(os.homedir(), '.config', 'session-manager'),
 ];
 
 /**
@@ -144,17 +143,15 @@ function validateWrite(realAbs) {
       if (realAbs === claudeSub || realAbs.startsWith(claudeSub + path.sep)) {
         return;
       }
-      // Writable ops namespaces under a registered project root — this
-      // repo's per-project artifact-store convention:
-      //   prompt-sessions  PromptSession persistence (promptSessions.ts) and
-      //                    the scheduler's read-modify-write of active-index
-      //                    (promptSessionEvents.cjs, PRD 814)
-      //   scheduler        PRD sources + Epic PRD dirs + state shards
-      //                    (PRD 825; scheduler.cjs remote.writePrd)
-      //   project-brief    projectBrief.cjs's brief.json (PRD 837)
-      //   bilko-host       bilkoHost.cjs's bundle prep
-      //   project-pages    projectHomeAdminRoutes.cjs's project_home_write
-      //                    path (home.html)
+      // Writable ops namespaces under a registered project root — every
+      // namespace declared in opsOwnership.cjs's OWNERS map is writable here
+      // by construction (PRD 1410): OWNERS is the single source of truth for
+      // "this namespace exists and has an owner", so a namespace can never
+      // again be declared owned yet unwritable (incident: PRD 1398 added
+      // 'ui-prefs' to OWNERS but this list was hand-maintained separately and
+      // never updated, so every ui-prefs write threw here before
+      // assertOpsWrite's per-writer check ever ran). Which WRITER may use a
+      // given namespace is still assertOpsWrite's job below, not this list's.
       // Paths come from opsOwnership.opsPath (PRD 1082) — the one ops-root
       // resolver — which THROWS for an ephemeral root (a linked worktree that
       // pty.cjs registered as an allowed root for its spawn cwd, or
@@ -162,7 +159,7 @@ function validateWrite(realAbs) {
       // never a writable destination, so its exemptions simply do not exist.
       let opsSubs;
       try {
-        opsSubs = ['prompt-sessions', 'scheduler', 'project-brief', 'bilko-host', 'project-pages'].map((ns) => opsPath(realRoot, ns));
+        opsSubs = Object.keys(OWNERS).map((ns) => opsPath(realRoot, ns));
       } catch {
         opsSubs = [];
       }
@@ -313,6 +310,20 @@ function writeJsonSync(abs, data, opts = {}) {
   return { ok: true, mtimeMs: stat.mtimeMs };
 }
 
+/**
+ * One-shot best-effort move of a legacy config file to its new home. No-op
+ * (silent) when the new path already exists or the old path never existed —
+ * either way there is nothing to migrate. Same-filesystem rename is atomic,
+ * so there is no partial-write window to worry about.
+ */
+function migrateLegacyHomeFile(oldPath, newPath) {
+  try {
+    if (fs.existsSync(newPath) || !fs.existsSync(oldPath)) return;
+    fs.mkdirSync(path.dirname(newPath), { recursive: true });
+    fs.renameSync(oldPath, newPath);
+  } catch { /* best-effort; a stale/missing legacy file must never block boot */ }
+}
+
 async function listDir(abs, { filesOnly = false, dirsOnly = false, includeHidden = false } = {}) {
   try {
     abs = validatePath(expandHome(abs));
@@ -490,6 +501,7 @@ module.exports = {
   readText,
   writeJson,
   writeJsonSync,
+  migrateLegacyHomeFile,
   writeTextAtomic,
   writeBinaryAtomic,
   listDir,

package/src/main/exchanges.cjs

@@ -3,8 +3,15 @@
 /**
  * exchanges.cjs — durable append-only log of completed terminal-chat exchanges.
  *
- * Appends one NDJSON record per successful chat run to:
- *   ~/.claude/knowledge-log/exchanges/<encodeCwd(cwd)>.jsonl
+ * Appends one NDJSON record per successful chat run to the per-project ops
+ * root (single-writer law, lib/opsOwnership.cjs — 'prompt-sessions' is owned
+ * by 'epics'):
+ *   <cwd>/session-manager-operations/prompt-sessions/exchanges.jsonl
+ *
+ * Historical rows from before this PRD live on, untouched, in the old global
+ * store (~/.claude/knowledge-log/exchanges/<encodeCwd(cwd)>.jsonl) — migrating
+ * them would require the same unsafe cwd-decoding this store is meant to
+ * avoid, so they are simply left behind; only new exchanges land here.
  *
  * Record shape (contract for PRDs 324 + 325):
  *   { ts, sessionId, cwd, prompt, result, summary, degraded?, promptId? }
@@ -20,31 +27,30 @@
  */
 
 const fsp = require('node:fs/promises');
-const fs = require('node:fs');
 const path = require('node:path');
-const os = require('node:os');
-const { encodeCwd } = require('./lib/encodeCwd.cjs');
-const { validatePath } = require('./config.cjs');
+const { opsPath, assertOpsWrite } = require('./lib/opsOwnership.cjs');
 const { summarize } = require('./lib/summarize.cjs');
 
-const HOME = os.homedir();
-const EXCHANGES_DIR = path.join(HOME, '.claude', 'knowledge-log', 'exchanges');
+const EXCHANGES_WRITER = 'epics';
+
+function exchangesFilePath(cwd) {
+  return opsPath(cwd, 'prompt-sessions', 'exchanges.jsonl');
+}
 
 /**
- * Record a completed exchange. Creates the exchanges directory if needed.
- * Appends one JSON line; uses O_APPEND so concurrent writes from separate
- * processes are safe (each line is a single write, POSIX O_APPEND atomic for
- * pipe-sized payloads).
+ * Record a completed exchange. Creates the ops directory if needed. Appends
+ * one JSON line via raw fs O_APPEND (not config.cjs's writeJson) so
+ * concurrent writes from separate processes stay safe — each line is a
+ * single write, POSIX O_APPEND atomic for pipe-sized payloads. Because this
+ * bypasses config.cjs's normal write boundary, the single-writer law is
+ * asserted explicitly here.
  *
  * @param {{ sessionId: string, cwd: string, prompt: string, result: string, promptId?: string }} opts
  * @returns {Promise<void>}
  */
 async function recordExchange({ sessionId, cwd, prompt, result, promptId }) {
-  const encoded = encodeCwd(cwd);
-  const filePath = path.join(EXCHANGES_DIR, `${encoded}.jsonl`);
-
-  // Security: validate that the target path stays within home dir
-  validatePath(EXCHANGES_DIR);
+  const filePath = exchangesFilePath(cwd);
+  assertOpsWrite(filePath, EXCHANGES_WRITER);
 
   // Summarize — always resolves; never throws
   const { summary, model, degraded } = await summarize(result);
@@ -63,7 +69,7 @@ async function recordExchange({ sessionId, cwd, prompt, result, promptId }) {
 
   const line = JSON.stringify(record) + '\n';
 
-  await fsp.mkdir(EXCHANGES_DIR, { recursive: true });
+  await fsp.mkdir(path.dirname(filePath), { recursive: true });
   await fsp.appendFile(filePath, line, { encoding: 'utf8' });
 }
 
@@ -79,8 +85,7 @@ const DEFAULT_LIMIT = 100;
  * @returns {Promise<object[]>}
  */
 async function listExchanges({ cwd, sessionId, limit = DEFAULT_LIMIT, offset = 0 }) {
-  const encoded = encodeCwd(cwd);
-  const filePath = path.join(EXCHANGES_DIR, `${encoded}.jsonl`);
+  const filePath = exchangesFilePath(cwd);
 
   let stat;
   try { stat = await fsp.stat(filePath); } catch { return []; }
@@ -128,4 +133,4 @@ async function listExchanges({ cwd, sessionId, limit = DEFAULT_LIMIT, offset = 0
   return filtered.slice(offset, offset + limit);
 }
 
-module.exports = { recordExchange, listExchanges, EXCHANGES_DIR };
+module.exports = { recordExchange, listExchanges };