onbuzz 3.4.0 → 3.6.2

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

@@ -0,0 +1,257 @@
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+import { createMockLogger, createMockConfig, createMockAiService, createMockStateManager, createMockAgentPool } from '../../__test-utils__/mockFactories.js';
+
+// Mock constants so the module loads without side effects
+jest.unstable_mockModule('../../utilities/constants.js', () => ({
+  INTERFACE_TYPES: { CLI: 'cli', WEB: 'web', VSCODE: 'vscode' },
+  AGENT_TYPES: { USER_CREATED: 'user-created', SYSTEM_AGENT: 'system-agent' },
+  AGENT_STATUS: { ACTIVE: 'active', IDLE: 'idle', BUSY: 'busy', PAUSED: 'paused', ERROR: 'error' },
+  MESSAGE_MODES: { CHAT: 'chat', AGENT: 'agent' },
+  ORCHESTRATOR_ACTIONS: {
+    CREATE_AGENT: 'create_agent',
+    UPDATE_AGENT: 'update_agent',
+    DELETE_AGENT: 'delete_agent',
+    UNLOAD_AGENT: 'unload_agent',
+    SEND_MESSAGE: 'send_message',
+    LIST_AGENTS: 'list_agents',
+    RESUME_SESSION: 'resume_session',
+    GET_SESSION_STATE: 'get_session_state',
+    PAUSE_AGENT: 'pause_agent',
+    RESUME_AGENT: 'resume_agent',
+    SWITCH_MODEL: 'switch_model',
+    GET_AGENT_STATUS: 'get_agent_status',
+    GET_AGENT_CONVERSATIONS: 'get_agent_conversations'
+  },
+  SYSTEM_DEFAULTS: {}
+}));
+
+const { default: Orchestrator } = await import('../orchestrator.js');
+
+describe('Orchestrator', () => {
+  let orchestrator;
+  let mockConfig;
+  let mockLogger;
+  let mockAgentPool;
+  let mockMessageProcessor;
+  let mockAiService;
+  let mockStateManager;
+
+  const makeRequest = (overrides = {}) => ({
+    interface: 'web',
+    sessionId: 'session-1',
+    action: 'send_message',
+    payload: {},
+    projectDir: '/test/project',
+    ...overrides
+  });
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+
+    mockConfig = createMockConfig();
+    mockLogger = createMockLogger();
+    mockAiService = createMockAiService();
+    mockStateManager = createMockStateManager();
+    mockAgentPool = createMockAgentPool();
+
+    // Add methods Orchestrator actually calls
+    mockAgentPool.listActiveAgents = jest.fn().mockResolvedValue([]);
+    mockAgentPool.pauseAgent = jest.fn().mockResolvedValue({ success: true });
+    mockAgentPool.resumeAgent = jest.fn().mockResolvedValue({ success: true });
+    mockAgentPool.restoreAgent = jest.fn().mockResolvedValue(undefined);
+    mockAgentPool.deleteAgent = jest.fn().mockResolvedValue({ success: true });
+    mockAgentPool.unloadAgent = jest.fn().mockResolvedValue({ success: true });
+
+    mockMessageProcessor = {
+      processMessage: jest.fn().mockResolvedValue({
+        success: true,
+        agentId: 'agent-1',
+        queuedAt: new Date().toISOString()
+      })
+    };
+
+    orchestrator = new Orchestrator(
+      mockConfig,
+      mockLogger,
+      mockAgentPool,
+      mockMessageProcessor,
+      mockAiService,
+      mockStateManager
+    );
+  });
+
+  // ───── Request Routing ─────
+
+  describe('processRequest routing', () => {
+    test('CREATE_AGENT action delegates to createAgent', async () => {
+      const createdAgent = { id: 'new-1', name: 'Builder', preferredModel: 'gpt-4' };
+      mockAgentPool.createAgent.mockResolvedValue(createdAgent);
+
+      const response = await orchestrator.processRequest(makeRequest({
+        action: 'create_agent',
+        payload: { name: 'Builder', systemPrompt: 'You build things', model: 'gpt-4' }
+      }));
+
+      expect(response.success).toBe(true);
+      expect(response.data.id).toBe('new-1');
+      expect(mockAgentPool.createAgent).toHaveBeenCalledTimes(1);
+    });
+
+    test('SEND_MESSAGE action delegates to routeToAgent', async () => {
+      const agent = {
+        id: 'agent-1', name: 'Agent', status: 'active',
+        currentModel: 'gpt-4', mode: 'chat'
+      };
+      mockAgentPool._agents.set('agent-1', agent);
+      mockAgentPool.getAgent.mockImplementation((id) => mockAgentPool._agents.get(id));
+
+      const response = await orchestrator.processRequest(makeRequest({
+        action: 'send_message',
+        payload: { agentId: 'agent-1', message: 'Hello agent' }
+      }));
+
+      expect(response.success).toBe(true);
+      expect(mockMessageProcessor.processMessage).toHaveBeenCalledWith(
+        'agent-1', 'Hello agent', expect.objectContaining({ sessionId: 'session-1' })
+      );
+    });
+
+    test('LIST_AGENTS action returns agent list', async () => {
+      const agents = [{ id: 'a1', name: 'Alpha' }, { id: 'a2', name: 'Beta' }];
+      mockAgentPool.listActiveAgents.mockResolvedValue(agents);
+
+      const response = await orchestrator.processRequest(makeRequest({
+        action: 'list_agents',
+        payload: {}
+      }));
+
+      expect(response.success).toBe(true);
+      expect(response.data).toEqual(agents);
+    });
+
+    test('unknown action returns error response', async () => {
+      const response = await orchestrator.processRequest(makeRequest({
+        action: 'totally_invalid_action',
+        payload: {}
+      }));
+
+      expect(response.success).toBe(false);
+      expect(response.error).toContain('Unknown action');
+    });
+
+    test('response includes metadata with timestamp, executionTime, sessionId', async () => {
+      mockAgentPool.listActiveAgents.mockResolvedValue([]);
+
+      const response = await orchestrator.processRequest(makeRequest({
+        action: 'list_agents',
+        payload: {}
+      }));
+
+      expect(response.metadata).toBeDefined();
+      expect(response.metadata.timestamp).toBeDefined();
+      expect(typeof response.metadata.executionTime).toBe('number');
+      expect(response.metadata.sessionId).toBe('session-1');
+    });
+  });
+
+  // ───── Session Management ─────
+
+  describe('session management', () => {
+    test('_ensureSession creates new session on first call', async () => {
+      expect(orchestrator.activeSessions.size).toBe(0);
+
+      await orchestrator._ensureSession('s-new', '/project');
+
+      expect(orchestrator.activeSessions.has('s-new')).toBe(true);
+      const session = orchestrator.activeSessions.get('s-new');
+      expect(session.projectDir).toBe('/project');
+      expect(session.createdAt).toBeDefined();
+    });
+
+    test('_ensureSession reuses existing session on subsequent calls', async () => {
+      await orchestrator._ensureSession('s-reuse', '/project');
+      const firstCreated = orchestrator.activeSessions.get('s-reuse').createdAt;
+
+      // Small delay to differentiate timestamps
+      await new Promise(r => setTimeout(r, 5));
+      await orchestrator._ensureSession('s-reuse', '/project');
+
+      expect(orchestrator.activeSessions.size).toBe(1);
+      // createdAt should remain unchanged
+      expect(orchestrator.activeSessions.get('s-reuse').createdAt).toBe(firstCreated);
+    });
+  });
+
+  // ───── Agent Operations ─────
+
+  describe('agent operations', () => {
+    test('routeToAgent with valid agent returns queued response', async () => {
+      const agent = { id: 'agent-1', name: 'Bot', status: 'active', currentModel: 'gpt-4' };
+      mockAgentPool.getAgent.mockResolvedValue(agent);
+
+      const result = await orchestrator.routeToAgent('agent-1', 'Do something', { sessionId: 's1' });
+
+      expect(result.success).toBe(true);
+      expect(result.data.status).toBe('queued');
+      expect(result.data.agentId).toBe('agent-1');
+    });
+
+    test('routeToAgent with paused agent throws error', async () => {
+      const futureDate = new Date(Date.now() + 60000).toISOString();
+      const agent = { id: 'agent-1', name: 'Bot', status: 'paused', pausedUntil: futureDate };
+      mockAgentPool.getAgent.mockResolvedValue(agent);
+
+      await expect(
+        orchestrator.routeToAgent('agent-1', 'Hey', {})
+      ).rejects.toThrow(/paused/);
+    });
+
+    test('createAgent delegates to agentPool.createAgent', async () => {
+      const created = { id: 'new-a', name: 'Fresh', preferredModel: 'claude-3' };
+      mockAgentPool.createAgent.mockResolvedValue(created);
+
+      const result = await orchestrator.createAgent('You are helpful', 'claude-3', { name: 'Fresh' });
+
+      expect(result.id).toBe('new-a');
+      expect(mockAgentPool.createAgent).toHaveBeenCalledWith(
+        expect.objectContaining({
+          name: 'Fresh',
+          systemPrompt: 'You are helpful',
+          preferredModel: 'claude-3'
+        })
+      );
+    });
+  });
+
+  // ───── Error Handling ─────
+
+  describe('error handling', () => {
+    test('processRequest catches errors and returns error response', async () => {
+      mockAgentPool.listActiveAgents.mockRejectedValue(new Error('pool exploded'));
+
+      const response = await orchestrator.processRequest(makeRequest({
+        action: 'list_agents',
+        payload: {}
+      }));
+
+      expect(response.success).toBe(false);
+      expect(response.error).toBe('pool exploded');
+      expect(response.metadata.timestamp).toBeDefined();
+    });
+
+    test('shutdown persists all agents and clears sessions', async () => {
+      const agents = [{ id: 'a1' }, { id: 'a2' }];
+      mockAgentPool.listActiveAgents.mockResolvedValue(agents);
+
+      // Pre-populate a session
+      orchestrator.activeSessions.set('s1', { id: 's1' });
+
+      await orchestrator.shutdown();
+
+      expect(mockStateManager.persistAgentState).toHaveBeenCalledTimes(2);
+      expect(mockStateManager.persistAgentState).toHaveBeenCalledWith('a1');
+      expect(mockStateManager.persistAgentState).toHaveBeenCalledWith('a2');
+      expect(orchestrator.activeSessions.size).toBe(0);
+    });
+  });
+});

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

@@ -0,0 +1,375 @@
+/**
+ * StateManager - Comprehensive unit tests (target: 80%+ line coverage)
+ * Tests directory initialization, state persistence, project state management,
+ * agent index operations, resume/restore flows, and error handling.
+ */
+import { jest, describe, test, expect, beforeEach } from '@jest/globals';
+import { createMockLogger, createMockConfig } from '../../__test-utils__/mockFactories.js';
+
+// ── Mock fs ──────────────────────────────────────────────────────────────────
+const mockMkdir = jest.fn().mockResolvedValue(undefined);
+const mockReadFile = jest.fn().mockResolvedValue('{}');
+const mockWriteFile = jest.fn().mockResolvedValue(undefined);
+const mockUnlink = jest.fn().mockResolvedValue(undefined);
+
+jest.unstable_mockModule('fs', () => ({
+  promises: {
+    mkdir: mockMkdir,
+    readFile: mockReadFile,
+    writeFile: mockWriteFile,
+    unlink: mockUnlink
+  }
+}));
+
+// ── Mock userDataDir ─────────────────────────────────────────────────────────
+const mockGetUserDataPaths = jest.fn().mockReturnValue({
+  base: '/mock/userdata',
+  state: '/mock/userdata/state',
+  agents: '/mock/userdata/state/agents',
+  logs: '/mock/userdata/logs'
+});
+const mockEnsureUserDataDirs = jest.fn().mockResolvedValue({
+  base: '/mock/userdata',
+  state: '/mock/userdata/state',
+  agents: '/mock/userdata/state/agents'
+});
+
+jest.unstable_mockModule('../../utilities/userDataDir.js', () => ({
+  getUserDataPaths: mockGetUserDataPaths,
+  ensureUserDataDirs: mockEnsureUserDataDirs
+}));
+
+const { default: StateManager } = await import('../stateManager.js');
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+function makeSM(configOverrides = {}) {
+  const config = createMockConfig(configOverrides);
+  const logger = createMockLogger();
+  const sm = new StateManager(config, logger);
+  return { sm, config, logger };
+}
+
+// ── Tests ────────────────────────────────────────────────────────────────────
+describe('StateManager', () => {
+  let sm, logger;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    ({ sm, logger } = makeSM());
+  });
+
+  // ─── Constructor ───────────────────────────────────────────────────────
+  describe('constructor', () => {
+    test('sets stateDirectory from userDataPaths', () => {
+      expect(sm.stateDirectory).toBe('/mock/userdata/state');
+    });
+
+    test('sets state file paths', () => {
+      expect(sm.stateFiles.projectState).toBe('project-state.json');
+      expect(sm.stateFiles.agentIndex).toBe('agent-index.json');
+    });
+
+    test('sets stateVersion', () => {
+      expect(sm.stateVersion).toBe('1.0.0');
+    });
+  });
+
+  // ─── getStateDir / getAgentsDir ────────────────────────────────────────
+  describe('getStateDir', () => {
+    test('returns persistent state directory (ignores projectDir)', () => {
+      expect(sm.getStateDir('/some/project')).toBe('/mock/userdata/state');
+    });
+  });
+
+  describe('getAgentsDir', () => {
+    test('returns agents directory', () => {
+      expect(sm.getAgentsDir()).toBe('/mock/userdata/state/agents');
+    });
+  });
+
+  // ─── initializeStateDirectory ──────────────────────────────────────────
+  describe('initializeStateDirectory', () => {
+    test('calls ensureUserDataDirs', async () => {
+      await sm.initializeStateDirectory('/project');
+      expect(mockEnsureUserDataDirs).toHaveBeenCalled();
+      expect(logger.info).toHaveBeenCalled();
+    });
+
+    test('throws and logs error when ensureUserDataDirs fails', async () => {
+      mockEnsureUserDataDirs.mockRejectedValueOnce(new Error('disk full'));
+      await expect(sm.initializeStateDirectory('/project')).rejects.toThrow('disk full');
+      expect(logger.error).toHaveBeenCalled();
+    });
+  });
+
+  // ─── loadProjectState ──────────────────────────────────────────────────
+  describe('loadProjectState', () => {
+    test('loads and returns project state from JSON file', async () => {
+      mockReadFile.mockResolvedValueOnce(JSON.stringify({ version: '1.0.0', projectDir: '/p' }));
+      const state = await sm.loadProjectState('/project');
+      expect(state.version).toBe('1.0.0');
+    });
+
+    test('creates default state when file does not exist', async () => {
+      mockReadFile.mockRejectedValueOnce(new Error('ENOENT'));
+      const state = await sm.loadProjectState('/project');
+      expect(state.version).toBe('1.0.0');
+      expect(state.activeAgents).toEqual([]);
+      // Should have saved the default state
+      expect(mockWriteFile).toHaveBeenCalled();
+    });
+  });
+
+  // ─── saveProjectState ──────────────────────────────────────────────────
+  describe('saveProjectState', () => {
+    test('writes project state JSON to disk', async () => {
+      await sm.saveProjectState('/project', { foo: 'bar' });
+      expect(mockMkdir).toHaveBeenCalled();
+      expect(mockWriteFile).toHaveBeenCalled();
+      const writtenData = JSON.parse(mockWriteFile.mock.calls[0][1]);
+      expect(writtenData.foo).toBe('bar');
+      expect(writtenData.lastModified).toBeDefined();
+    });
+  });
+
+  // ─── getProjectState ──────────────────────────────────────────────────
+  describe('getProjectState', () => {
+    test('delegates to loadProjectState', async () => {
+      mockReadFile.mockResolvedValueOnce(JSON.stringify({ version: '1.0.0' }));
+      const state = await sm.getProjectState('/project');
+      expect(state.version).toBe('1.0.0');
+    });
+  });
+
+  // ─── loadAgentIndex ────────────────────────────────────────────────────
+  describe('loadAgentIndex', () => {
+    test('returns parsed agent index', async () => {
+      const index = { 'agent-1': { name: 'Agent1' } };
+      mockReadFile.mockResolvedValueOnce(JSON.stringify(index));
+      const result = await sm.loadAgentIndex('/project');
+      expect(result['agent-1'].name).toBe('Agent1');
+    });
+
+    test('returns empty object when file missing', async () => {
+      mockReadFile.mockRejectedValueOnce(new Error('ENOENT'));
+      const result = await sm.loadAgentIndex('/project');
+      expect(result).toEqual({});
+    });
+  });
+
+  // ─── updateAgentIndex ──────────────────────────────────────────────────
+  describe('updateAgentIndex', () => {
+    test('adds agent info to index and saves', async () => {
+      mockReadFile.mockResolvedValueOnce(JSON.stringify({}));
+      const agent = {
+        id: 'agent-test',
+        name: 'Test',
+        type: 'user-created',
+        lastActivity: new Date().toISOString(),
+        currentModel: 'model-x',
+        status: 'active',
+        capabilities: ['terminal']
+      };
+      await sm.updateAgentIndex(agent, '/project');
+      expect(mockWriteFile).toHaveBeenCalled();
+      const written = JSON.parse(mockWriteFile.mock.calls[0][1]);
+      expect(written['agent-test'].name).toBe('Test');
+      expect(written['agent-test'].stateFile).toContain('agent-test');
+    });
+
+    test('creates new index when loadJSON fails', async () => {
+      mockReadFile.mockRejectedValueOnce(new Error('ENOENT'));
+      const agent = { id: 'a1', name: 'A', type: 'system', lastActivity: '', currentModel: 'm', status: 'active', capabilities: [] };
+      await sm.updateAgentIndex(agent, '/project');
+      expect(mockWriteFile).toHaveBeenCalled();
+    });
+  });
+
+  // ─── persistAgentState ─────────────────────────────────────────────────
+  describe('persistAgentState', () => {
+    test('saves agent state and conversations as separate files', async () => {
+      // First call: updateAgentIndex -> loadJSON for index
+      mockReadFile.mockResolvedValueOnce(JSON.stringify({}));
+
+      const agent = {
+        id: 'agent-persist',
+        name: 'PersistAgent',
+        type: 'user-created',
+        conversations: {
+          full: { messages: [{ role: 'user', content: 'hi' }] }
+        },
+        lastActivity: new Date().toISOString(),
+        currentModel: 'model-x',
+        status: 'active',
+        capabilities: []
+      };
+
+      await sm.persistAgentState(agent);
+
+      // Should have written state file and conversations file and index
+      expect(mockWriteFile).toHaveBeenCalledTimes(3); // state, conversations, index
+      const stateCall = mockWriteFile.mock.calls[0];
+      expect(stateCall[0]).toContain('agent-persist-state.json');
+      const convCall = mockWriteFile.mock.calls[1];
+      expect(convCall[0]).toContain('agent-persist-conversations.json');
+    });
+
+    test('throws on write failure', async () => {
+      mockWriteFile.mockRejectedValueOnce(new Error('write fail'));
+      const agent = { id: 'fail', conversations: { full: {} }, name: 'F', type: 't', lastActivity: '', currentModel: 'm', status: 'a', capabilities: [] };
+      await expect(sm.persistAgentState(agent)).rejects.toThrow('write fail');
+      expect(logger.error).toHaveBeenCalled();
+    });
+  });
+
+  // ─── deleteAgentState ──────────────────────────────────────────────────
+  describe('deleteAgentState', () => {
+    test('unlinks state and conversations files', async () => {
+      mockReadFile.mockResolvedValueOnce(JSON.stringify({ 'agent-del': { name: 'Del' } }));
+      await sm.deleteAgentState('agent-del');
+      expect(mockUnlink).toHaveBeenCalledTimes(2);
+    });
+
+    test('handles ENOENT gracefully (files already missing)', async () => {
+      const enoent = new Error('ENOENT');
+      enoent.code = 'ENOENT';
+      mockUnlink.mockRejectedValueOnce(enoent);
+      mockUnlink.mockRejectedValueOnce(enoent);
+      // removeFromAgentIndex calls loadJSON
+      mockReadFile.mockResolvedValueOnce(JSON.stringify({}));
+      await sm.deleteAgentState('agent-missing');
+      // Should not throw
+    });
+  });
+
+  // ─── resumeProject ────────────────────────────────────────────────────
+  describe('resumeProject', () => {
+    test('loads project state, agent index, and restores agents', async () => {
+      // Setup mock responses in order:
+      // 1. initializeStateDirectory -> ensureUserDataDirs (already mocked)
+      // 2. loadProjectState -> loadJSON
+      mockReadFile.mockResolvedValueOnce(JSON.stringify({ version: '1.0.0' }));
+      // 3. loadAgentIndex -> loadJSON
+      mockReadFile.mockResolvedValueOnce(JSON.stringify({}));
+      // 4. restoreAsyncOperations -> loadJSON
+      mockReadFile.mockRejectedValueOnce(new Error('ENOENT'));
+      // 5. restorePausedAgents -> loadJSON
+      mockReadFile.mockRejectedValueOnce(new Error('ENOENT'));
+      // 6. restoreContextReferences -> loadJSON
+      mockReadFile.mockRejectedValueOnce(new Error('ENOENT'));
+      // 7. saveLastSession -> saveJSON -> writeFile
+      // (writeFile is already mocked)
+
+      const result = await sm.resumeProject('/project');
+      expect(result.resumedSuccessfully).toBe(true);
+      expect(result.agents).toEqual([]);
+      expect(result.asyncOperations).toEqual([]);
+    });
+
+    test('returns error state on failure', async () => {
+      mockEnsureUserDataDirs.mockRejectedValueOnce(new Error('init fail'));
+      const result = await sm.resumeProject('/project');
+      expect(result.resumedSuccessfully).toBe(false);
+      expect(result.error).toContain('init fail');
+    });
+  });
+
+  // ─── saveJSON / loadJSON ───────────────────────────────────────────────
+  describe('saveJSON (private)', () => {
+    test('creates directory and writes JSON', 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'
+      );
+    });
+  });
+
+  describe('loadJSON (private)', () => {
+    test('reads and parses JSON', async () => {
+      mockReadFile.mockResolvedValueOnce(JSON.stringify({ x: 1 }));
+      const result = await sm.loadJSON('/path/to/file.json');
+      expect(result.x).toBe(1);
+    });
+
+    test('throws on corrupt JSON', async () => {
+      mockReadFile.mockResolvedValueOnce('not-json{{{');
+      await expect(sm.loadJSON('/bad.json')).rejects.toThrow();
+    });
+
+    test('throws on missing file', async () => {
+      mockReadFile.mockRejectedValueOnce(new Error('ENOENT'));
+      await expect(sm.loadJSON('/missing.json')).rejects.toThrow('ENOENT');
+    });
+  });
+
+  // ─── restoreAsyncOperations ────────────────────────────────────────────
+  describe('restoreAsyncOperations', () => {
+    test('returns operations from stored data', async () => {
+      mockReadFile.mockResolvedValueOnce(JSON.stringify({ operations: [{ id: 'op1' }] }));
+      const ops = await sm.restoreAsyncOperations('/project');
+      expect(ops).toEqual([{ id: 'op1' }]);
+    });
+
+    test('returns empty array on missing file', async () => {
+      mockReadFile.mockRejectedValueOnce(new Error('ENOENT'));
+      const ops = await sm.restoreAsyncOperations('/project');
+      expect(ops).toEqual([]);
+    });
+  });
+
+  // ─── restorePausedAgents ───────────────────────────────────────────────
+  describe('restorePausedAgents', () => {
+    test('returns paused agents data and resumes expired', async () => {
+      const past = new Date(Date.now() - 10000).toISOString();
+      mockReadFile.mockResolvedValueOnce(JSON.stringify({
+        pausedAgents: {
+          'agent-1': { pausedAt: past, pausedUntil: past, reason: 'test' }
+        }
+      }));
+      const result = await sm.restorePausedAgents('/project');
+      // Expired agent should be moved to history
+      expect(result.pausedAgents['agent-1']).toBeUndefined();
+      expect(result.pauseHistory).toHaveLength(1);
+    });
+
+    test('returns defaults on missing file', async () => {
+      mockReadFile.mockRejectedValueOnce(new Error('ENOENT'));
+      const result = await sm.restorePausedAgents('/project');
+      expect(result.pausedAgents).toEqual({});
+      expect(result.pauseHistory).toEqual([]);
+    });
+  });
+
+  // ─── restoreContextReferences ──────────────────────────────────────────
+  describe('restoreContextReferences', () => {
+    test('validates and returns references', async () => {
+      mockReadFile.mockResolvedValueOnce(JSON.stringify({
+        references: [{ id: 'ref1', type: 'file' }]
+      }));
+      const result = await sm.restoreContextReferences('/project');
+      expect(result.references).toHaveLength(1);
+      expect(result.references[0].isValid).toBe(true);
+    });
+
+    test('returns defaults on missing file', async () => {
+      mockReadFile.mockRejectedValueOnce(new Error('ENOENT'));
+      const result = await sm.restoreContextReferences('/project');
+      expect(result.references).toEqual([]);
+    });
+  });
+
+  // ─── saveLastSession / loadLastSession ─────────────────────────────────
+  describe('saveLastSession', () => {
+    test('writes session data with savedAt timestamp', async () => {
+      await sm.saveLastSession('/project', { agentCount: 2 });
+      expect(mockWriteFile).toHaveBeenCalled();
+      const written = JSON.parse(mockWriteFile.mock.calls[0][1]);
+      expect(written.agentCount).toBe(2);
+      expect(written.savedAt).toBeDefined();
+      expect(written.projectDir).toBe('/project');
+    });
+  });
+});