onbuzz 5.4.1 → 5.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "onbuzz",
-  "version": "5.4.1",
+  "version": "5.4.3",
   "description": "Loxia OnBuzz - Your AI Fleet",
   "type": "module",
   "main": "src/index.js",
@@ -13,7 +13,9 @@
     "terminal-ui": "node bin/loxia-terminal.js",
     "terminal-ui-v2": "node bin/loxia-terminal-v2.js",
     "start:terminal": "node bin/start-with-terminal.js",
-    "test": "NODE_OPTIONS='--experimental-vm-modules' jest",
+    "test": "NODE_OPTIONS='--experimental-vm-modules' jest --selectProjects unit",
+    "test:e2e": "NODE_OPTIONS='--experimental-vm-modules' jest --selectProjects e2e",
+    "test:all": "NODE_OPTIONS='--experimental-vm-modules' jest",
     "lint": "eslint src/",
     "typecheck": "echo 'No TypeScript - skipping typecheck'",
     "build": "npm run build:web-ui",

package/src/core/__tests__/agentScheduler.rateLimitEscalation.test.js

@@ -0,0 +1,243 @@
+/**
+ * Rate-limit escalation ladder + per-model cooldown.
+ *
+ * Behavioural contract (see handleAIServiceFailure's isRateLimit branch):
+ *   • Strikes are counted PER MODEL (limits are per provider+model, shared by
+ *     every agent using it) and decay after RATE_LIMIT_STRIKE_WINDOW_MS.
+ *   • Strikes 1..N-1 → QUIET 60s cooldown: no agent_error, no model_error;
+ *     just an agent_state_updated hint ('rate-limit') + delayEndTime.
+ *   • Strike N (RATE_LIMIT_ESCALATION_STRIKES) → broadcast model_error WITH
+ *     modelSuggestions (switch-model modal — now also for non-stream paths)
+ *     and a longer RATE_LIMIT_ESCALATED_DELAY_MS backoff.
+ *   • Every strike also cools down OTHER agents on the same model, staggered
+ *     MODEL_COOLDOWN_STAGGER_MS apart, never shortening an existing delay.
+ *   • Provider-overload keeps its own longer PROVIDER_OVERLOAD_DELAY_MS lane.
+ *
+ * Also pins aiService.isTransientModelError — the predicate that keeps the
+ * switch-model modal from firing on the FIRST 429 mid-stream.
+ */
+
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+import { createMockLogger } from '../../__test-utils__/mockFactories.js';
+import { SCHEDULER_CONFIG } from '../../utilities/constants.js';
+
+const mockShouldAgentBeActive = jest.fn(() => ({ active: false, reason: 'idle' }));
+const mockGetActiveAgents = jest.fn(() => []);
+const mockShouldSkipIteration = jest.fn(() => false);
+jest.unstable_mockModule('../../services/agentActivityService.js', () => ({
+  shouldAgentBeActive: mockShouldAgentBeActive,
+  getActiveAgents: mockGetActiveAgents,
+  shouldSkipIteration: mockShouldSkipIteration,
+}));
+
+const { default: AgentScheduler } = await import('../agentScheduler.js');
+const { default: AIService } = await import('../../services/aiService.js');
+
+const SUGGESTIONS = {
+  failedModel: 'model-a',
+  errorType: 'rate_limit',
+  errorMessage: 'HTTP 429 Too Many Requests',
+  suggestions: [{ name: 'model-b', displayName: 'Model B', provider: 'p', verified: true, successCount: 5, failureCount: 0 }],
+};
+
+function makeAgent(id, model = 'model-a', extra = {}) {
+  return {
+    id,
+    name: `Agent-${id}`,
+    sessionId: 'sess-1',
+    currentModel: model,
+    conversations: {
+      full: { messages: [], lastUpdated: null },
+      [model]: { messages: [], lastUpdated: null },
+    },
+    ...extra,
+  };
+}
+
+function makeScheduler({ agents = [makeAgent('a1')] } = {}) {
+  const logger = createMockLogger();
+  const byId = new Map(agents.map(a => [a.id, a]));
+  const agentPool = {
+    getAgent: jest.fn(async (id) => byId.get(id) || null),
+    getAllAgents: jest.fn(async () => [...byId.values()]),
+    persistAgentState: jest.fn().mockResolvedValue(undefined),
+    addToolResult: jest.fn().mockResolvedValue(undefined),
+  };
+  const broadcasts = [];
+  const webSocketManager = {
+    broadcastToSession: jest.fn((sessionId, payload) => broadcasts.push({ sessionId, payload })),
+  };
+  const aiService = {
+    abortRequest: jest.fn(),
+    getActiveRequest: () => null,
+    getModelSuggestions: jest.fn(() => SUGGESTIONS),
+  };
+  const scheduler = new AgentScheduler(agentPool, {}, aiService, logger);
+  scheduler.webSocketManager = webSocketManager;
+  const stateUpdates = [];
+  scheduler.broadcastAgentStateUpdate = jest.fn(async (agentId, reason) => stateUpdates.push({ agentId, reason }));
+  scheduler.getAgentSession = jest.fn(() => 'sess-1');
+  return { scheduler, agentPool, broadcasts, stateUpdates, agents: byId, logger, aiService };
+}
+
+const rateLimitError = () => new Error('HTTP 429 Too Many Requests');
+const modelErrors = (broadcasts) => broadcasts.filter(b => b.payload?.type === 'model_error');
+
+describe('rate-limit escalation ladder', () => {
+  test('strike 1: quiet ~60s cooldown, NO model_error, NO agent_error', async () => {
+    const { scheduler, broadcasts, stateUpdates, agents } = makeScheduler();
+    const before = Date.now();
+
+    await scheduler.handleAIServiceFailure('a1', rateLimitError());
+
+    const delay = new Date(agents.get('a1').delayEndTime).getTime() - before;
+    expect(delay).toBeGreaterThanOrEqual(SCHEDULER_CONFIG.RATE_LIMIT_DELAY_MS - 2000);
+    expect(delay).toBeLessThanOrEqual(SCHEDULER_CONFIG.RATE_LIMIT_DELAY_MS + 10_000);
+    expect(modelErrors(broadcasts)).toHaveLength(0);
+    expect(broadcasts.filter(b => b.payload?.type === 'agent_error')).toHaveLength(0);
+    expect(stateUpdates).toContainEqual({ agentId: 'a1', reason: 'rate-limit' });
+  });
+
+  test('strike 2 stays quiet; strike 3 broadcasts model_error with suggestions + longer delay', async () => {
+    const { scheduler, broadcasts, agents, aiService } = makeScheduler();
+
+    await scheduler.handleAIServiceFailure('a1', rateLimitError());
+    await scheduler.handleAIServiceFailure('a1', rateLimitError());
+    expect(modelErrors(broadcasts)).toHaveLength(0); // two failed cooldowns, still quiet
+
+    const before = Date.now();
+    await scheduler.handleAIServiceFailure('a1', rateLimitError());
+
+    const errs = modelErrors(broadcasts);
+    expect(errs).toHaveLength(1);
+    expect(errs[0].payload.data.modelSuggestions).toEqual(SUGGESTIONS);
+    expect(errs[0].payload.data.agentId).toBe('a1');
+    expect(errs[0].payload.data.escalatedFromRateLimit).toBe(true);
+    expect(aiService.getModelSuggestions).toHaveBeenCalledWith('model-a', expect.any(Error));
+
+    // Escalated backoff (2 min), not the quiet 60s.
+    const delay = new Date(agents.get('a1').delayEndTime).getTime() - before;
+    expect(delay).toBeGreaterThanOrEqual(SCHEDULER_CONFIG.RATE_LIMIT_ESCALATED_DELAY_MS - 2000);
+  });
+
+  test('strikes are per MODEL: two agents on the same model share the count', async () => {
+    const { scheduler, broadcasts } = makeScheduler({
+      agents: [makeAgent('a1', 'model-a'), makeAgent('a2', 'model-a')],
+    });
+    await scheduler.handleAIServiceFailure('a1', rateLimitError()); // strike 1 (model-a)
+    await scheduler.handleAIServiceFailure('a2', rateLimitError()); // strike 2 (model-a)
+    await scheduler.handleAIServiceFailure('a1', rateLimitError()); // strike 3 → escalate
+    expect(modelErrors(broadcasts)).toHaveLength(1);
+  });
+
+  test('strikes decay after the quiet window (old bad minute forgiven)', async () => {
+    const { scheduler, broadcasts } = makeScheduler();
+    await scheduler.handleAIServiceFailure('a1', rateLimitError());
+    await scheduler.handleAIServiceFailure('a1', rateLimitError());
+
+    // Age the entry past the window — the next strike restarts at 1.
+    const entry = scheduler._modelRateLimits.get('model-a');
+    entry.lastStrikeAt = Date.now() - SCHEDULER_CONFIG.RATE_LIMIT_STRIKE_WINDOW_MS - 1000;
+
+    await scheduler.handleAIServiceFailure('a1', rateLimitError());
+    expect(modelErrors(broadcasts)).toHaveLength(0); // would have been strike 3 without decay
+    expect(scheduler._modelRateLimits.get('model-a').strikes).toBe(1);
+  });
+
+  test('missing getModelSuggestions degrades gracefully (no broadcast, no crash)', async () => {
+    const { scheduler, broadcasts, aiService } = makeScheduler();
+    delete aiService.getModelSuggestions;
+    await scheduler.handleAIServiceFailure('a1', rateLimitError());
+    await scheduler.handleAIServiceFailure('a1', rateLimitError());
+    await scheduler.handleAIServiceFailure('a1', rateLimitError()); // escalation point
+    expect(modelErrors(broadcasts)).toHaveLength(0);
+  });
+});
+
+describe('per-model cooldown (shared-limit spillover)', () => {
+  test('other agents on the SAME model get staggered delays; other models untouched', async () => {
+    const { scheduler, stateUpdates, agents } = makeScheduler({
+      agents: [
+        makeAgent('a1', 'model-a'),
+        makeAgent('a2', 'model-a'),
+        makeAgent('a3', 'model-a'),
+        makeAgent('b1', 'model-b'),
+      ],
+    });
+    const before = Date.now();
+
+    await scheduler.handleAIServiceFailure('a1', rateLimitError());
+
+    const end = (id) => new Date(agents.get(id).delayEndTime).getTime();
+    // a2 and a3 cooled down, staggered one step apart.
+    const base = before + SCHEDULER_CONFIG.RATE_LIMIT_DELAY_MS;
+    expect(end('a2')).toBeGreaterThanOrEqual(base + SCHEDULER_CONFIG.MODEL_COOLDOWN_STAGGER_MS - 2000);
+    expect(end('a3') - end('a2')).toBeGreaterThanOrEqual(SCHEDULER_CONFIG.MODEL_COOLDOWN_STAGGER_MS - 1000);
+    expect(end('a3') - end('a2')).toBeLessThanOrEqual(SCHEDULER_CONFIG.MODEL_COOLDOWN_STAGGER_MS + 5000);
+    // Different model: untouched.
+    expect(agents.get('b1').delayEndTime).toBeUndefined();
+    // Spillover agents get the dedicated reason tag (UI: silent chip, no toast).
+    expect(stateUpdates).toContainEqual({ agentId: 'a2', reason: 'rate-limit-cooldown' });
+    expect(stateUpdates).toContainEqual({ agentId: 'a3', reason: 'rate-limit-cooldown' });
+  });
+
+  test('never SHORTENS an existing longer delay', async () => {
+    const longEnd = new Date(Date.now() + 60 * 60 * 1000).toISOString(); // 1h pause
+    const { scheduler, agents } = makeScheduler({
+      agents: [makeAgent('a1', 'model-a'), makeAgent('a2', 'model-a', { delayEndTime: longEnd })],
+    });
+    await scheduler.handleAIServiceFailure('a1', rateLimitError());
+    expect(agents.get('a2').delayEndTime).toBe(longEnd);
+  });
+
+  test('agentPool without getAllAgents degrades gracefully (source agent still delayed)', async () => {
+    const { scheduler, agentPool, agents } = makeScheduler();
+    delete agentPool.getAllAgents;
+    await scheduler.handleAIServiceFailure('a1', rateLimitError());
+    expect(agents.get('a1').delayEndTime).toBeTruthy();
+  });
+});
+
+describe('provider-overload keeps its own longer lane', () => {
+  test('529 uses PROVIDER_OVERLOAD_DELAY_MS (2 min), not the 60s rate-limit cooldown', async () => {
+    const { scheduler, agents } = makeScheduler();
+    const before = Date.now();
+    await scheduler.handleAIServiceFailure('a1', new Error('HTTP 529 Overloaded'));
+    const delay = new Date(agents.get('a1').delayEndTime).getTime() - before;
+    expect(delay).toBeGreaterThanOrEqual(SCHEDULER_CONFIG.PROVIDER_OVERLOAD_DELAY_MS - 2000);
+    expect(delay).toBeLessThanOrEqual(SCHEDULER_CONFIG.PROVIDER_OVERLOAD_DELAY_MS + 10_000);
+  });
+});
+
+describe('aiService.isTransientModelError (modal gating predicate)', () => {
+  // Pure classification — call the prototype directly to avoid constructing
+  // the full service.
+  const isTransient = (err) => AIService.prototype.isTransientModelError.call({}, err);
+
+  test.each([
+    ['Rate limit exceeded'],
+    ['HTTP 429 Too Many Requests'],
+    ['quota exceeded for this billing period'],
+    ['The model is overloaded'],
+    ['Provider returned a capacity error'],
+    ['HTTP 503 Service Unavailable'],
+    ['HTTP 529 Overloaded'],
+  ])('transient: "%s"', (msg) => {
+    expect(isTransient(new Error(msg))).toBe(true);
+  });
+
+  test('transient via status code without matching message', () => {
+    const err = new Error('request failed');
+    err.status = 429;
+    expect(isTransient(err)).toBe(true);
+  });
+
+  test.each([
+    ['Model claude-x not found'],
+    ['invalid model specified'],
+    ['unsupported model for this account'],
+    ['Random 500 Internal Server Error'],
+  ])('NOT transient (modal fires immediately): "%s"', (msg) => {
+    expect(isTransient(new Error(msg))).toBe(false);
+  });
+});

package/src/core/__tests__/stateManager.atomicWrite.test.js

@@ -0,0 +1,150 @@
+/**
+ * StateManager.saveJSON — atomic, serialized writes (corruption prevention).
+ *
+ * Two real corruptions were traced to unsafe writes: a save interrupted
+ * mid-write left a truncated file, and two overlapping saves of the same file
+ * left a short new write sitting on top of a longer old one. saveJSON now:
+ *   - writes to a unique temp file then renames it over the target (atomic —
+ *     a crash damages only the throwaway temp, never the live file),
+ *   - retries the transient Windows EPERM/EACCES/EBUSY rename races,
+ *   - serializes writes PER target path so concurrent saves can't interleave.
+ *
+ * These tests pin that contract against a mocked fs.
+ */
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+import { createMockLogger, createMockConfig } from '../../__test-utils__/mockFactories.js';
+
+const mockMkdir = jest.fn().mockResolvedValue(undefined);
+const mockWriteFile = jest.fn().mockResolvedValue(undefined);
+const mockRename = jest.fn().mockResolvedValue(undefined);
+const mockUnlink = jest.fn().mockResolvedValue(undefined);
+const mockReadFile = jest.fn().mockResolvedValue('{}');
+const mockReaddir = jest.fn().mockResolvedValue([]);
+
+jest.unstable_mockModule('fs', () => ({
+  promises: {
+    mkdir: mockMkdir,
+    writeFile: mockWriteFile,
+    rename: mockRename,
+    unlink: mockUnlink,
+    readFile: mockReadFile,
+    readdir: mockReaddir,
+  },
+}));
+
+jest.unstable_mockModule('../../utilities/userDataDir.js', () => ({
+  getUserDataPaths: jest.fn().mockReturnValue({
+    base: '/mock/userdata', state: '/mock/userdata/state', agents: '/mock/userdata/state/agents', logs: '/mock/userdata/logs',
+  }),
+  ensureUserDataDirs: jest.fn().mockResolvedValue({}),
+}));
+
+const { default: StateManager } = await import('../stateManager.js');
+const makeSM = () => new StateManager(createMockConfig(), createMockLogger());
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  mockMkdir.mockResolvedValue(undefined);
+  mockWriteFile.mockResolvedValue(undefined);
+  mockRename.mockResolvedValue(undefined);
+  mockUnlink.mockResolvedValue(undefined);
+});
+
+describe('saveJSON — atomic write', () => {
+  test('writes to a temp file then renames it over the target', async () => {
+    const sm = makeSM();
+    await sm.saveJSON('/mock/userdata/state/x.json', { a: 1 });
+
+    const [wpath, contents] = mockWriteFile.mock.calls[0];
+    expect(wpath).toMatch(/x\.json\.\d+\.\d+\.tmp$/); // unique temp beside the target
+    expect(wpath).not.toBe('/mock/userdata/state/x.json');
+    expect(JSON.parse(contents)).toEqual({ a: 1 });
+    expect(mockRename).toHaveBeenCalledWith(wpath, '/mock/userdata/state/x.json');
+  });
+
+  test('NEVER writes the live target path directly (only the temp is written)', async () => {
+    const sm = makeSM();
+    await sm.saveJSON('/mock/userdata/state/y.json', { b: 2 });
+    for (const [p] of mockWriteFile.mock.calls) {
+      expect(p).not.toBe('/mock/userdata/state/y.json');
+    }
+  });
+
+  test('cleans up the temp and rethrows if the write fails (live file untouched)', async () => {
+    const sm = makeSM();
+    mockWriteFile.mockRejectedValueOnce(new Error('disk full'));
+    await expect(sm.saveJSON('/mock/userdata/state/z.json', {})).rejects.toThrow('disk full');
+    expect(mockUnlink).toHaveBeenCalledTimes(1);   // temp cleaned
+    expect(mockRename).not.toHaveBeenCalled();      // never swapped a broken temp in
+  });
+
+  test('retries a transient EPERM rename, then succeeds (Windows sharing violation)', async () => {
+    const sm = makeSM();
+    const eperm = Object.assign(new Error('perm'), { code: 'EPERM' });
+    mockRename.mockRejectedValueOnce(eperm).mockRejectedValueOnce(eperm).mockResolvedValueOnce(undefined);
+    await sm.saveJSON('/mock/userdata/state/r.json', {});
+    expect(mockRename).toHaveBeenCalledTimes(3);
+    expect(mockUnlink).not.toHaveBeenCalled(); // ultimately succeeded — no cleanup
+  });
+
+  test('gives up after exhausting rename retries and cleans the temp', async () => {
+    const sm = makeSM();
+    mockRename.mockRejectedValue(Object.assign(new Error('busy'), { code: 'EBUSY' }));
+    await expect(sm.saveJSON('/mock/userdata/state/r2.json', {})).rejects.toThrow('busy');
+    expect(mockRename).toHaveBeenCalledTimes(5);
+    expect(mockUnlink).toHaveBeenCalledTimes(1);
+  });
+
+  test('a non-transient rename error is NOT retried', async () => {
+    const sm = makeSM();
+    mockRename.mockRejectedValue(Object.assign(new Error('nospace'), { code: 'ENOSPC' }));
+    await expect(sm.saveJSON('/mock/userdata/state/r3.json', {})).rejects.toThrow('nospace');
+    expect(mockRename).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('saveJSON — per-path serialization', () => {
+  test('two concurrent saves of the SAME path do not interleave', async () => {
+    const sm = makeSM();
+    const events = [];
+    let releaseRename1;
+    mockWriteFile.mockImplementation(async () => { events.push('write'); });
+    mockRename
+      .mockImplementationOnce(async () => { events.push('rename1-start'); await new Promise((r) => { releaseRename1 = r; }); events.push('rename1-done'); })
+      .mockImplementationOnce(async () => { events.push('rename2'); });
+
+    const pA = sm.saveJSON('/mock/userdata/state/same.json', { n: 1 });
+    const pB = sm.saveJSON('/mock/userdata/state/same.json', { n: 2 });
+
+    // Let microtasks flush: B must be blocked behind A's (still-running) rename.
+    await new Promise((r) => setTimeout(r, 10));
+    expect(mockWriteFile).toHaveBeenCalledTimes(1);
+    expect(events).toEqual(['write', 'rename1-start']);
+
+    releaseRename1();
+    await Promise.all([pA, pB]);
+    // A fully completes before B even starts writing — no interleave.
+    expect(events).toEqual(['write', 'rename1-start', 'rename1-done', 'write', 'rename2']);
+  });
+
+  test('a failed write does not block later writes to the same path', async () => {
+    const sm = makeSM();
+    mockWriteFile.mockRejectedValueOnce(new Error('boom')); // first (A) write fails
+    const a = sm.saveJSON('/mock/userdata/state/same2.json', {}).catch((e) => e.message);
+    const b = sm.saveJSON('/mock/userdata/state/same2.json', { ok: true });
+    expect(await a).toBe('boom');
+    await expect(b).resolves.toBeUndefined();
+    expect(mockRename).toHaveBeenCalledTimes(1); // only B renamed; A failed before its rename
+  });
+
+  test('writes to DIFFERENT paths are independent (a stalled one does not block another)', async () => {
+    const sm = makeSM();
+    let releaseSlow;
+    mockRename.mockImplementationOnce(async () => { await new Promise((r) => { releaseSlow = r; }); }); // path A hangs in rename
+    const slow = sm.saveJSON('/mock/userdata/state/slow.json', {});
+    const fast = sm.saveJSON('/mock/userdata/state/fast.json', {}); // different path
+    await expect(fast).resolves.toBeUndefined(); // completes without waiting for slow
+    releaseSlow();
+    await slow;
+  });
+});

package/src/core/__tests__/stateManager.snippetCache.test.js

@@ -20,6 +20,8 @@ const mockReadFile = jest.fn().mockResolvedValue('{}');
 const mockWriteFile = jest.fn().mockResolvedValue(undefined);
 const mockUnlink = jest.fn().mockResolvedValue(undefined);
 const mockReaddir = jest.fn().mockResolvedValue([]);
+// saveJSON now writes atomically: writeFile(<path>.tmp) then rename(tmp -> path).
+const mockRename = jest.fn().mockResolvedValue(undefined);
 
 jest.unstable_mockModule('fs', () => ({
   promises: {
@@ -28,6 +30,7 @@ jest.unstable_mockModule('fs', () => ({
     writeFile: mockWriteFile,
     unlink: mockUnlink,
     readdir: mockReaddir,
+    rename: mockRename,
   },
 }));
 
@@ -136,6 +139,7 @@ describe('StateManager — snippet caching', () => {
     mockReadFile.mockResolvedValue('{}');
     mockWriteFile.mockResolvedValue(undefined);
     mockReaddir.mockResolvedValue([]);
+    mockRename.mockResolvedValue(undefined);
     ({ sm, logger } = makeSM());
   });
 
@@ -195,14 +199,31 @@ describe('StateManager — snippet caching', () => {
     expect(written['a1'].firstUserMessage).toBe('from disk');
   });
 
-  test('archived cache MISS with missing conv file -> snippet stays undefined, no persist', async () => {
-    mockReadFile.mockRejectedValueOnce(new Error('ENOENT'));
+  test('archived cache MISS with MISSING conv file (ENOENT) -> snippet stays undefined, no persist (retry next time)', async () => {
+    const enoent = Object.assign(new Error('no such file'), { code: 'ENOENT' });
+    mockReadFile.mockRejectedValueOnce(enoent);
     const agents = [{ agentId: 'a1', isLoaded: false, conversationsFile: 'agents/a1-conv.json' }];
     await sm._enrichAgentsWithSnippets(agents, null, '/p');
     expect(agents[0].firstUserMessage).toBeUndefined();
     expect(mockWriteFile).not.toHaveBeenCalled();
   });
 
+  // The perf bug: a conversations file that EXISTS but can't be parsed (corrupt
+  // JSON, or too large to parse) used to be left undefined = a permanent cache
+  // miss, re-read (tens of MB) on EVERY list call forever. It must now be cached
+  // as null so the file is touched once and skipped thereafter.
+  test('archived cache MISS with CORRUPT conv file -> caches null + persists (read once, never again)', async () => {
+    const parseErr = new SyntaxError('Unexpected end of JSON input'); // no .code, like a real JSON.parse throw
+    mockReadFile
+      .mockRejectedValueOnce(parseErr)                              // the corrupt conversations read
+      .mockResolvedValueOnce(JSON.stringify({ a1: { name: 'A' } })); // index load inside _persistAgentSnippets
+    const agents = [{ agentId: 'a1', isLoaded: false, conversationsFile: 'agents/a1-conv.json' }];
+    await sm._enrichAgentsWithSnippets(agents, null, '/p');
+    expect(agents[0].firstUserMessage).toBe(null);
+    const written = JSON.parse(mockWriteFile.mock.calls[0][1]);
+    expect(written['a1'].firstUserMessage).toBe(null); // cached — next list is a hit, no re-read
+  });
+
   test('loaded agent but pool returns null -> falls through to disk', async () => {
     const agentPool = { getAgent: jest.fn().mockResolvedValue(null) };
     mockReadFile
@@ -383,8 +404,10 @@ describe('StateManager — snippet caching', () => {
       return '{}';
     });
     // Capture the backfill write so the 2nd call "sees" the warmed index.
+    // saveJSON writes to "<...>agent-index.json.<pid>.<n>.tmp", so match a
+    // substring rather than the exact suffix.
     mockWriteFile.mockImplementation(async (p, body) => {
-      if (String(p).endsWith('agent-index.json')) persisted = JSON.parse(body);
+      if (String(p).includes('agent-index.json')) persisted = JSON.parse(body);
     });
     mockReaddir.mockResolvedValue(['agent-a1-state.json']);
     const agentPool = { getAllAgents: jest.fn().mockResolvedValue([]) };

package/src/core/__tests__/stateManager.test.js

@@ -12,6 +12,8 @@ const mockReadFile = jest.fn().mockResolvedValue('{}');
 const mockWriteFile = jest.fn().mockResolvedValue(undefined);
 const mockUnlink = jest.fn().mockResolvedValue(undefined);
 const mockReaddir = jest.fn().mockResolvedValue([]);
+// saveJSON now writes atomically: writeFile(<path>.tmp) then rename(tmp -> path).
+const mockRename = jest.fn().mockResolvedValue(undefined);
 
 jest.unstable_mockModule('fs', () => ({
   promises: {
@@ -19,7 +21,8 @@ jest.unstable_mockModule('fs', () => ({
     readFile: mockReadFile,
     writeFile: mockWriteFile,
     unlink: mockUnlink,
-    readdir: mockReaddir
+    readdir: mockReaddir,
+    rename: mockRename
   }
 }));
 
@@ -57,6 +60,7 @@ describe('StateManager', () => {
 
   beforeEach(() => {
     jest.clearAllMocks();
+    mockRename.mockResolvedValue(undefined);
     ({ sm, logger } = makeSM());
   });
 
@@ -278,14 +282,18 @@ describe('StateManager', () => {
 
   // ─── saveJSON / loadJSON ───────────────────────────────────────────────
   describe('saveJSON (private)', () => {
-    test('creates directory and writes JSON', async () => {
+    test('creates directory and writes JSON atomically (temp + rename)', async () => {
       await sm.saveJSON('/path/to/file.json', { key: 'value' });
       expect(mockMkdir).toHaveBeenCalledWith(expect.any(String), { recursive: true });
-      expect(mockWriteFile).toHaveBeenCalledWith(
-        '/path/to/file.json',
-        expect.any(String),
-        'utf8'
-      );
+      // Atomic write: the payload goes to a unique temp beside the target...
+      const [tmpPath, contents, enc] = mockWriteFile.mock.calls[0];
+      expect(tmpPath).toMatch(/^\/path\/to\/file\.json\.\d+\.\d+\.tmp$/);
+      expect(JSON.parse(contents)).toEqual({ key: 'value' });
+      expect(enc).toBe('utf8');
+      // ...then it's renamed over the live file.
+      expect(mockRename).toHaveBeenCalledWith(tmpPath, '/path/to/file.json');
+      // The live path is never written directly.
+      expect(mockWriteFile).not.toHaveBeenCalledWith('/path/to/file.json', expect.anything(), expect.anything());
     });
   });