@ai-devkit/agent-manager 0.14.0 → 0.16.0

package/src/__tests__/AgentManager.test.ts

@@ -2,16 +2,20 @@
  * Tests for AgentManager
  */
 
-import { describe, it, expect, beforeEach } from '@jest/globals';
-import { AgentManager } from '../AgentManager';
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { AgentManager } from '../AgentManager.js';
 import type {
     AgentAdapter,
     AgentInfo,
     AgentType,
     ConversationMessage,
     SessionSummary,
-} from '../adapters/AgentAdapter';
-import { AgentStatus } from '../adapters/AgentAdapter';
+} from '../adapters/AgentAdapter.js';
+import { AgentStatus } from '../adapters/AgentAdapter.js';
+import { AgentRegistry, type RegistryEntry } from '../utils/AgentRegistry.js';
 
 // Mock adapter for testing
 class MockAdapter implements AgentAdapter {
@@ -240,6 +244,137 @@ describe('AgentManager', () => {
         });
     });
 
+    describe('listAgents — registry persistence', () => {
+        let tmpDir: string;
+        let regPath: string;
+        let registry: AgentRegistry;
+        let scopedManager: AgentManager;
+
+        beforeEach(() => {
+            tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-manager-'));
+            regPath = path.join(tmpDir, 'agents.json');
+            registry = new AgentRegistry(regPath);
+            scopedManager = new AgentManager(registry);
+        });
+
+        afterEach(() => {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        });
+
+        it('persists every detected agent to the registry', async () => {
+            scopedManager.registerAdapter(new MockAdapter('claude', [
+                createMockAgent({
+                    name: 'a',
+                    pid: process.pid,
+                    sessionId: 'sid-a',
+                    sessionFilePath: '/path/a.jsonl',
+                    projectPath: '/cwd/a',
+                }),
+            ]));
+
+            await scopedManager.listAgents();
+
+            const entries = registry.list();
+            expect(entries).toHaveLength(1);
+            expect(entries[0]).toMatchObject({
+                name: 'a',
+                type: 'claude',
+                pid: process.pid,
+                cwd: '/cwd/a',
+                sessionId: 'sid-a',
+                sessionFilePath: '/path/a.jsonl',
+                tmuxSession: '',
+            });
+            expect(entries[0].startedAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+        });
+
+        it('prunes entries for dead pids', async () => {
+            registry.register({
+                name: 'dead',
+                type: 'claude',
+                pid: 999999,
+                tmuxSession: '',
+                cwd: '/cwd/dead',
+                startedAt: '2026-05-30T00:00:00.000Z',
+                sessionId: 'sid-dead',
+                sessionFilePath: '/path/dead.jsonl',
+            });
+
+            scopedManager.registerAdapter(new MockAdapter('claude', [
+                createMockAgent({ name: 'live', pid: process.pid }),
+            ]));
+
+            await scopedManager.listAgents();
+
+            const entries = registry.list();
+            expect(entries.map((e) => e.name)).toEqual(['live']);
+        });
+
+        it('preserves an existing name (e.g. user-set "merry") across cycles', async () => {
+            registry.register({
+                name: 'merry',
+                type: 'claude',
+                pid: process.pid,
+                tmuxSession: 'merry',
+                cwd: '/cwd/merry',
+                startedAt: '2026-05-30T00:00:00.000Z',
+                sessionId: 'sid-merry',
+                sessionFilePath: '/path/merry.jsonl',
+            });
+
+            scopedManager.registerAdapter(new MockAdapter('claude', [
+                createMockAgent({ name: 'default-name', pid: process.pid }),
+            ]));
+
+            const agents = await scopedManager.listAgents();
+
+            expect(agents[0].name).toBe('merry');
+            expect(registry.list()[0].name).toBe('merry');
+            expect(registry.list()[0].tmuxSession).toBe('merry');
+            expect(registry.list()[0].startedAt).toBe('2026-05-30T00:00:00.000Z');
+        });
+
+        it('writes a fresh startedAt for new entries', async () => {
+            const before = new Date().toISOString();
+            scopedManager.registerAdapter(new MockAdapter('claude', [
+                createMockAgent({ name: 'new', pid: process.pid }),
+            ]));
+
+            await scopedManager.listAgents();
+
+            const entry = registry.list()[0];
+            expect(entry.startedAt >= before).toBe(true);
+        });
+
+        it('batches the write — a single registerBatch call per listAgents', async () => {
+            const spy = vi.spyOn(registry, 'registerBatch');
+
+            scopedManager.registerAdapter(new MockAdapter('claude', [
+                createMockAgent({ name: 'a', pid: process.pid }),
+            ]));
+            scopedManager.registerAdapter(new MockAdapter('codex', [
+                createMockAgent({ name: 'b', type: 'codex', pid: process.pid + 1 }),
+            ]));
+
+            await scopedManager.listAgents();
+
+            expect(spy).toHaveBeenCalledTimes(1);
+            expect((spy.mock.calls[0][0] as RegistryEntry[]).map((e) => e.name).sort())
+                .toEqual(['a', 'b']);
+        });
+
+        it('skips registerBatch when no agents detected (still calls prune)', async () => {
+            const writeSpy = vi.spyOn(registry, 'registerBatch');
+            const pruneSpy = vi.spyOn(registry, 'prune');
+
+            scopedManager.registerAdapter(new MockAdapter('claude', []));
+            await scopedManager.listAgents();
+
+            expect(writeSpy).not.toHaveBeenCalled();
+            expect(pruneSpy).toHaveBeenCalledTimes(1);
+        });
+    });
+
     describe('clear', () => {
         it('should remove all adapters', () => {
             manager.registerAdapter(new MockAdapter('claude'));
@@ -333,7 +468,7 @@ describe('AgentManager', () => {
                 new MockAdapter('codex', [], false, [], true /* failListSessions */),
             );
 
-            const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => undefined);
+            const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
 
             try {
                 const result = await manager.listSessions();

package/src/__tests__/adapters/ClaudeCodeAdapter.test.ts

@@ -2,40 +2,42 @@
  * Tests for ClaudeCodeAdapter
  */
 
+import type { MockedFunction } from 'vitest';
 import * as fs from 'fs';
 import * as path from 'path';
-import { describe, it, expect, beforeEach, afterEach, jest } from '@jest/globals';
-import { ClaudeCodeAdapter } from '../../adapters/ClaudeCodeAdapter';
-import type { ProcessInfo } from '../../adapters/AgentAdapter';
-import { AgentStatus } from '../../adapters/AgentAdapter';
-import { listAgentProcesses, enrichProcesses } from '../../utils/process';
-import { batchGetSessionFileBirthtimes } from '../../utils/session';
-import type { SessionFile } from '../../utils/session';
-import { matchProcessesToSessions, generateAgentName } from '../../utils/matching';
-import type { MatchResult } from '../../utils/matching';
-jest.mock('../../utils/process', () => ({
-    listAgentProcesses: jest.fn(),
-    enrichProcesses: jest.fn(),
+
+import { ClaudeCodeAdapter } from '../../adapters/ClaudeCodeAdapter.js';
+import type { ProcessInfo } from '../../adapters/AgentAdapter.js';
+import { AgentStatus } from '../../adapters/AgentAdapter.js';
+import { listAgentProcesses, enrichProcesses } from '../../utils/process.js';
+import { batchGetSessionFileBirthtimes } from '../../utils/session.js';
+import type { SessionFile } from '../../utils/session.js';
+import { matchProcessesToSessions, generateAgentName } from '../../utils/matching.js';
+import type { MatchResult } from '../../utils/matching.js';
+import * as os from 'os';
+vi.mock('../../utils/process.js', () => ({
+    listAgentProcesses: vi.fn(),
+    enrichProcesses: vi.fn(),
 }));
 
-jest.mock('../../utils/session', () => {
-    const actual = jest.requireActual('../../utils/session') as typeof import('../../utils/session');
+vi.mock('../../utils/session.js', async () => {
+    const actual = await vi.importActual('../../utils/session') as typeof import('../../utils/session');
     return {
         ...actual,
-        batchGetSessionFileBirthtimes: jest.fn(),
+        batchGetSessionFileBirthtimes: vi.fn(),
     };
 });
 
-jest.mock('../../utils/matching', () => ({
-    matchProcessesToSessions: jest.fn(),
-    generateAgentName: jest.fn(),
+vi.mock('../../utils/matching.js', () => ({
+    matchProcessesToSessions: vi.fn(),
+    generateAgentName: vi.fn(),
 }));
 
-const mockedListAgentProcesses = listAgentProcesses as jest.MockedFunction<typeof listAgentProcesses>;
-const mockedEnrichProcesses = enrichProcesses as jest.MockedFunction<typeof enrichProcesses>;
-const mockedBatchGetSessionFileBirthtimes = batchGetSessionFileBirthtimes as jest.MockedFunction<typeof batchGetSessionFileBirthtimes>;
-const mockedMatchProcessesToSessions = matchProcessesToSessions as jest.MockedFunction<typeof matchProcessesToSessions>;
-const mockedGenerateAgentName = generateAgentName as jest.MockedFunction<typeof generateAgentName>;
+const mockedListAgentProcesses = listAgentProcesses as MockedFunction<typeof listAgentProcesses>;
+const mockedEnrichProcesses = enrichProcesses as MockedFunction<typeof enrichProcesses>;
+const mockedBatchGetSessionFileBirthtimes = batchGetSessionFileBirthtimes as MockedFunction<typeof batchGetSessionFileBirthtimes>;
+const mockedMatchProcessesToSessions = matchProcessesToSessions as MockedFunction<typeof matchProcessesToSessions>;
+const mockedGenerateAgentName = generateAgentName as MockedFunction<typeof generateAgentName>;
 describe('ClaudeCodeAdapter', () => {
     let adapter: ClaudeCodeAdapter;
 
@@ -163,7 +165,7 @@ describe('ClaudeCodeAdapter', () => {
             mockedEnrichProcesses.mockReturnValue(processes);
 
             // Set up projects dir with encoded directory name
-            const tmpDir = fs.mkdtempSync(path.join(require('os').tmpdir(), 'claude-test-'));
+            const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'claude-test-'));
             const projectsDir = path.join(tmpDir, 'projects');
             // Claude encodes /Users/test/my-project → -Users-test-my-project
             const projDir = path.join(projectsDir, '-Users-test-my-project');
@@ -222,7 +224,7 @@ describe('ClaudeCodeAdapter', () => {
             mockedEnrichProcesses.mockReturnValue(processes);
 
             // Set up projects dir with encoded directory names
-            const tmpDir = fs.mkdtempSync(path.join(require('os').tmpdir(), 'claude-test-'));
+            const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'claude-test-'));
             const projectsDir = path.join(tmpDir, 'projects');
             // /project-a → -project-a, /project-b → -project-b
             const projDirA = path.join(projectsDir, '-project-a');
@@ -303,7 +305,7 @@ describe('ClaudeCodeAdapter', () => {
             mockedListAgentProcesses.mockReturnValue(processes);
             mockedEnrichProcesses.mockReturnValue(processes);
 
-            const tmpDir = fs.mkdtempSync(path.join(require('os').tmpdir(), 'claude-resume-'));
+            const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'claude-resume-'));
             const projectsDir = path.join(tmpDir, 'projects');
             const projDir = path.join(projectsDir, '-project-resumed');
             fs.mkdirSync(projDir, { recursive: true });
@@ -367,7 +369,7 @@ describe('ClaudeCodeAdapter', () => {
             mockedListAgentProcesses.mockReturnValue(processes);
             mockedEnrichProcesses.mockReturnValue(processes);
 
-            const tmpDir = fs.mkdtempSync(path.join(require('os').tmpdir(), 'claude-pid-test-'));
+            const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'claude-pid-test-'));
             const sessionsDir = path.join(tmpDir, 'sessions');
             const projectsDir = path.join(tmpDir, 'projects');
             const projDir = path.join(projectsDir, '-project-direct');
@@ -416,7 +418,7 @@ describe('ClaudeCodeAdapter', () => {
             mockedListAgentProcesses.mockReturnValue(processes);
             mockedEnrichProcesses.mockReturnValue(processes);
 
-            const tmpDir = fs.mkdtempSync(path.join(require('os').tmpdir(), 'claude-pid-wait-'));
+            const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'claude-pid-wait-'));
             const sessionsDir = path.join(tmpDir, 'sessions');
             const projectsDir = path.join(tmpDir, 'projects');
             const projDir = path.join(projectsDir, '-project-wait');
@@ -425,8 +427,7 @@ describe('ClaudeCodeAdapter', () => {
 
             const sessionId = 'wait-session';
             const jsonlPath = path.join(projDir, `${sessionId}.jsonl`);
-            // JSONL trails with permission-mode → parser would resolve to UNKNOWN.
-            // PID file's live status must win.
+            // PID file's live status must win over JSONL-derived status.
             fs.writeFileSync(jsonlPath, [
                 JSON.stringify({ type: 'user', timestamp: new Date().toISOString(), cwd: '/project/wait', message: { content: '/reddit-commenter' } }),
                 JSON.stringify({ type: 'permission-mode', timestamp: new Date().toISOString(), permissionMode: 'default' }),
@@ -463,7 +464,7 @@ describe('ClaudeCodeAdapter', () => {
             mockedListAgentProcesses.mockReturnValue(processes);
             mockedEnrichProcesses.mockReturnValue(processes);
 
-            const tmpDir = fs.mkdtempSync(path.join(require('os').tmpdir(), 'claude-pid-idle-'));
+            const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'claude-pid-idle-'));
             const sessionsDir = path.join(tmpDir, 'sessions');
             const projectsDir = path.join(tmpDir, 'projects');
             const projDir = path.join(projectsDir, '-project-idle');
@@ -508,7 +509,7 @@ describe('ClaudeCodeAdapter', () => {
             mockedListAgentProcesses.mockReturnValue(processes);
             mockedEnrichProcesses.mockReturnValue(processes);
 
-            const tmpDir = fs.mkdtempSync(path.join(require('os').tmpdir(), 'claude-pid-nostat-'));
+            const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'claude-pid-nostat-'));
             const sessionsDir = path.join(tmpDir, 'sessions');
             const projectsDir = path.join(tmpDir, 'projects');
             const projDir = path.join(projectsDir, '-project-legacy');
@@ -560,7 +561,7 @@ describe('ClaudeCodeAdapter', () => {
             mockedListAgentProcesses.mockReturnValue(processes);
             mockedEnrichProcesses.mockReturnValue(processes);
 
-            const tmpDir = fs.mkdtempSync(path.join(require('os').tmpdir(), 'claude-resume-wait-'));
+            const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'claude-resume-wait-'));
             const sessionsDir = path.join(tmpDir, 'sessions');
             const projectsDir = path.join(tmpDir, 'projects');
             const projDir = path.join(projectsDir, '-project-resume-wait');
@@ -604,7 +605,7 @@ describe('ClaudeCodeAdapter', () => {
             mockedListAgentProcesses.mockReturnValue(processes);
             mockedEnrichProcesses.mockReturnValue(processes);
 
-            const tmpDir = fs.mkdtempSync(path.join(require('os').tmpdir(), 'claude-gone-'));
+            const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'claude-gone-'));
             const sessionsDir = path.join(tmpDir, 'sessions');
             const projectsDir = path.join(tmpDir, 'projects');
             const projDir = path.join(projectsDir, '-project-gone');
@@ -623,7 +624,7 @@ describe('ClaudeCodeAdapter', () => {
             (adapter as any).projectsDir = projectsDir;
 
             // Simulate JSONL disappearing between existence check and read
-            jest.spyOn((adapter as any).parser, 'readSession').mockReturnValueOnce(null);
+            vi.spyOn((adapter as any).parser, 'readSession').mockReturnValueOnce(null);
 
             const agents = await adapter.detectAgents();
 
@@ -633,7 +634,7 @@ describe('ClaudeCodeAdapter', () => {
             expect(agents[0].status).toBe(AgentStatus.IDLE);
 
             fs.rmSync(tmpDir, { recursive: true, force: true });
-            jest.restoreAllMocks();
+            vi.restoreAllMocks();
         });
 
         it('should fall back to process-only when legacy-matched JSONL becomes unreadable', async () => {
@@ -644,7 +645,7 @@ describe('ClaudeCodeAdapter', () => {
             mockedListAgentProcesses.mockReturnValue(processes);
             mockedEnrichProcesses.mockReturnValue(processes);
 
-            const tmpDir = fs.mkdtempSync(path.join(require('os').tmpdir(), 'claude-lgone-'));
+            const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'claude-lgone-'));
             const projectsDir = path.join(tmpDir, 'projects');
             const projDir = path.join(projectsDir, '-project-legacy-gone');
             fs.mkdirSync(projDir, { recursive: true });
@@ -670,7 +671,7 @@ describe('ClaudeCodeAdapter', () => {
             ]);
 
             // Simulate JSONL disappearing between match and read
-            jest.spyOn((adapter as any).parser, 'readSession').mockReturnValueOnce(null);
+            vi.spyOn((adapter as any).parser, 'readSession').mockReturnValueOnce(null);
 
             const agents = await adapter.detectAgents();
 
@@ -679,7 +680,7 @@ describe('ClaudeCodeAdapter', () => {
             expect(agents[0].status).toBe(AgentStatus.IDLE);
 
             fs.rmSync(tmpDir, { recursive: true, force: true });
-            jest.restoreAllMocks();
+            vi.restoreAllMocks();
         });
 
         it('should mix direct PID-file matches and legacy matches across processes', async () => {
@@ -691,7 +692,7 @@ describe('ClaudeCodeAdapter', () => {
             mockedListAgentProcesses.mockReturnValue(processes);
             mockedEnrichProcesses.mockReturnValue(processes);
 
-            const tmpDir = fs.mkdtempSync(path.join(require('os').tmpdir(), 'claude-mix-test-'));
+            const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'claude-mix-test-'));
             const sessionsDir = path.join(tmpDir, 'sessions');
             const projectsDir = path.join(tmpDir, 'projects');
             const projAlpha = path.join(projectsDir, '-project-alpha');
@@ -756,7 +757,7 @@ describe('ClaudeCodeAdapter', () => {
         let tmpDir: string;
 
         beforeEach(() => {
-            tmpDir = fs.mkdtempSync(path.join(require('os').tmpdir(), 'claude-test-'));
+            tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'claude-test-'));
         });
 
         afterEach(() => {
@@ -1071,7 +1072,7 @@ describe('ClaudeCodeAdapter', () => {
         let tmpDir: string;
 
         beforeEach(() => {
-            tmpDir = fs.mkdtempSync(path.join(require('os').tmpdir(), 'claude-test-'));
+            tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'claude-test-'));
         });
 
         afterEach(() => {
@@ -1419,7 +1420,7 @@ describe('ClaudeCodeAdapter', () => {
         let tmpDir: string;
 
         beforeEach(() => {
-            tmpDir = fs.mkdtempSync(path.join(require('os').tmpdir(), 'claude-conv-'));
+            tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'claude-conv-'));
         });
 
         afterEach(() => {
@@ -1594,7 +1595,7 @@ describe('ClaudeCodeAdapter', () => {
         let projectsDir: string;
 
         beforeEach(() => {
-            tmpDir = fs.mkdtempSync(path.join(require('os').tmpdir(), 'claude-list-'));
+            tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'claude-list-'));
             projectsDir = path.join(tmpDir, 'projects');
             fs.mkdirSync(projectsDir, { recursive: true });
             (adapter as any).projectsDir = projectsDir;

package/src/__tests__/adapters/CodexAdapter.test.ts

@@ -2,41 +2,44 @@
  * Tests for CodexAdapter
  */
 
+import type { MockedFunction } from 'vitest';
 import * as fs from 'fs';
 import * as path from 'path';
-import { beforeEach, afterEach, describe, expect, it, jest } from '@jest/globals';
-import { CodexAdapter } from '../../adapters/CodexAdapter';
-import type { ProcessInfo } from '../../adapters/AgentAdapter';
-import { AgentStatus } from '../../adapters/AgentAdapter';
-import { listAgentProcesses, enrichProcesses } from '../../utils/process';
-import { batchGetSessionFileBirthtimes } from '../../utils/session';
-import type { SessionFile } from '../../utils/session';
-import { matchProcessesToSessions, generateAgentName } from '../../utils/matching';
-import type { MatchResult } from '../../utils/matching';
-
-jest.mock('../../utils/process', () => ({
-    listAgentProcesses: jest.fn(),
-    enrichProcesses: jest.fn(),
+
+import { CodexAdapter } from '../../adapters/CodexAdapter.js';
+import type { ProcessInfo } from '../../adapters/AgentAdapter.js';
+import { AgentStatus } from '../../adapters/AgentAdapter.js';
+import { AgentRegistry, type RegistryEntry } from '../../utils/AgentRegistry.js';
+import { listAgentProcesses, enrichProcesses } from '../../utils/process.js';
+import { batchGetSessionFileBirthtimes } from '../../utils/session.js';
+import type { SessionFile } from '../../utils/session.js';
+import { matchProcessesToSessions, generateAgentName } from '../../utils/matching.js';
+import type { MatchResult } from '../../utils/matching.js';
+import * as os from 'os';
+
+vi.mock('../../utils/process.js', () => ({
+    listAgentProcesses: vi.fn(),
+    enrichProcesses: vi.fn(),
 }));
 
-jest.mock('../../utils/session', () => {
-    const actual = jest.requireActual('../../utils/session') as typeof import('../../utils/session');
+vi.mock('../../utils/session.js', async () => {
+    const actual = await vi.importActual('../../utils/session') as typeof import('../../utils/session');
     return {
         ...actual,
-        batchGetSessionFileBirthtimes: jest.fn(),
+        batchGetSessionFileBirthtimes: vi.fn(),
     };
 });
 
-jest.mock('../../utils/matching', () => ({
-    matchProcessesToSessions: jest.fn(),
-    generateAgentName: jest.fn(),
+vi.mock('../../utils/matching.js', () => ({
+    matchProcessesToSessions: vi.fn(),
+    generateAgentName: vi.fn(),
 }));
 
-const mockedListAgentProcesses = listAgentProcesses as jest.MockedFunction<typeof listAgentProcesses>;
-const mockedEnrichProcesses = enrichProcesses as jest.MockedFunction<typeof enrichProcesses>;
-const mockedBatchGetSessionFileBirthtimes = batchGetSessionFileBirthtimes as jest.MockedFunction<typeof batchGetSessionFileBirthtimes>;
-const mockedMatchProcessesToSessions = matchProcessesToSessions as jest.MockedFunction<typeof matchProcessesToSessions>;
-const mockedGenerateAgentName = generateAgentName as jest.MockedFunction<typeof generateAgentName>;
+const mockedListAgentProcesses = listAgentProcesses as MockedFunction<typeof listAgentProcesses>;
+const mockedEnrichProcesses = enrichProcesses as MockedFunction<typeof enrichProcesses>;
+const mockedBatchGetSessionFileBirthtimes = batchGetSessionFileBirthtimes as MockedFunction<typeof batchGetSessionFileBirthtimes>;
+const mockedMatchProcessesToSessions = matchProcessesToSessions as MockedFunction<typeof matchProcessesToSessions>;
+const mockedGenerateAgentName = generateAgentName as MockedFunction<typeof generateAgentName>;
 
 describe('CodexAdapter', () => {
     let adapter: CodexAdapter;
@@ -136,7 +139,7 @@ describe('CodexAdapter', () => {
             mockedEnrichProcesses.mockReturnValue(processes);
 
             // Set up sessions dir with date directory
-            const tmpDir = fs.mkdtempSync(path.join(require('os').tmpdir(), 'codex-test-'));
+            const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codex-test-'));
             const sessionsDir = path.join(tmpDir, 'sessions');
             const dateDir = path.join(sessionsDir, '2026', '03', '18');
             fs.mkdirSync(dateDir, { recursive: true });
@@ -195,7 +198,7 @@ describe('CodexAdapter', () => {
             mockedListAgentProcesses.mockReturnValue(processes);
             mockedEnrichProcesses.mockReturnValue(processes);
 
-            const tmpDir = fs.mkdtempSync(path.join(require('os').tmpdir(), 'codex-test-'));
+            const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codex-test-'));
             const sessionsDir = path.join(tmpDir, 'sessions');
             const now = new Date();
             const dateDir = path.join(
@@ -247,11 +250,115 @@ describe('CodexAdapter', () => {
         });
     });
 
+    describe('detectAgents — registry cache short-circuit', () => {
+        let tmpDir: string;
+        let regPath: string;
+        let registry: AgentRegistry;
+        let cachedAdapter: CodexAdapter;
+        let sessionFilePath: string;
+
+        function registerEntry(over: Partial<RegistryEntry> = {}): void {
+            registry.register({
+                name: 'codex-100',
+                type: 'codex',
+                pid: 100,
+                tmuxSession: '',
+                cwd: '/repo-a',
+                startedAt: '2026-05-30T00:00:00.000Z',
+                sessionId: 'sess-cached',
+                sessionFilePath,
+                ...over,
+            });
+        }
+
+        beforeEach(() => {
+            tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codex-cache-'));
+            regPath = path.join(tmpDir, 'agents.json');
+            registry = new AgentRegistry(regPath);
+            cachedAdapter = new CodexAdapter(registry);
+
+            const recentTs = new Date().toISOString();
+            sessionFilePath = path.join(tmpDir, 'sess-cached.jsonl');
+            fs.writeFileSync(sessionFilePath, [
+                JSON.stringify({ type: 'session_meta', payload: { id: 'sess-cached', timestamp: recentTs, cwd: '/repo-a' } }),
+                JSON.stringify({ type: 'event', timestamp: recentTs, payload: { type: 'token_count', message: 'Hello from cache' } }),
+            ].join('\n'));
+        });
+
+        afterEach(() => {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        });
+
+        it('short-circuits matching when registry has a valid entry', async () => {
+            registerEntry();
+            const processes: ProcessInfo[] = [
+                { pid: 100, command: 'codex', cwd: '/repo-a', tty: 'ttys001', startTime: new Date() },
+            ];
+            mockedListAgentProcesses.mockReturnValue(processes);
+            mockedEnrichProcesses.mockReturnValue(processes);
+
+            const agents = await cachedAdapter.detectAgents();
+
+            expect(agents).toHaveLength(1);
+            expect(agents[0]).toMatchObject({
+                type: 'codex',
+                pid: 100,
+                sessionId: 'sess-cached',
+                sessionFilePath,
+                summary: 'Hello from cache',
+            });
+            expect(mockedMatchProcessesToSessions).not.toHaveBeenCalled();
+            expect(mockedBatchGetSessionFileBirthtimes).not.toHaveBeenCalled();
+        });
+
+        it('falls through when no registry entry exists for the pid', async () => {
+            const processes: ProcessInfo[] = [
+                { pid: 100, command: 'codex', cwd: '/repo-a', tty: 'ttys001', startTime: new Date() },
+            ];
+            mockedListAgentProcesses.mockReturnValue(processes);
+            mockedEnrichProcesses.mockReturnValue(processes);
+            (cachedAdapter as any).codexSessionsDir = '/nonexistent';
+
+            const agents = await cachedAdapter.detectAgents();
+
+            expect(agents[0].sessionId).toBe('pid-100');
+        });
+
+        it('falls through when registry entry type does not match', async () => {
+            registerEntry({ type: 'claude' });
+            const processes: ProcessInfo[] = [
+                { pid: 100, command: 'codex', cwd: '/repo-a', tty: 'ttys001', startTime: new Date() },
+            ];
+            mockedListAgentProcesses.mockReturnValue(processes);
+            mockedEnrichProcesses.mockReturnValue(processes);
+            (cachedAdapter as any).codexSessionsDir = '/nonexistent';
+
+            const agents = await cachedAdapter.detectAgents();
+
+            expect(agents[0].sessionId).toBe('pid-100');
+            expect(mockedMatchProcessesToSessions).not.toHaveBeenCalled();
+        });
+
+        it('falls through when the cached session file no longer exists', async () => {
+            registerEntry({ sessionFilePath: path.join(tmpDir, 'deleted.jsonl') });
+            const processes: ProcessInfo[] = [
+                { pid: 100, command: 'codex', cwd: '/repo-a', tty: 'ttys001', startTime: new Date() },
+            ];
+            mockedListAgentProcesses.mockReturnValue(processes);
+            mockedEnrichProcesses.mockReturnValue(processes);
+            (cachedAdapter as any).codexSessionsDir = '/nonexistent';
+
+            const agents = await cachedAdapter.detectAgents();
+
+            expect(agents[0].sessionId).toBe('pid-100');
+        });
+    });
+
     describe('discoverSessions', () => {
         let tmpDir: string;
 
         beforeEach(() => {
-            tmpDir = fs.mkdtempSync(path.join(require('os').tmpdir(), 'codex-test-'));
+            tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codex-test-'));
         });
 
         afterEach(() => {
@@ -399,7 +506,7 @@ describe('CodexAdapter', () => {
             let tmpDir: string;
 
             beforeEach(() => {
-                tmpDir = fs.mkdtempSync(path.join(require('os').tmpdir(), 'codex-test-'));
+                tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codex-test-'));
             });
 
             afterEach(() => {
@@ -524,7 +631,7 @@ describe('CodexAdapter', () => {
         let tmpDir: string;
 
         beforeEach(() => {
-            tmpDir = fs.mkdtempSync(path.join(require('os').tmpdir(), 'codex-conv-'));
+            tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codex-conv-'));
         });
 
         afterEach(() => {
@@ -640,7 +747,7 @@ describe('CodexAdapter', () => {
         let sessionsDir: string;
 
         beforeEach(() => {
-            tmpDir = fs.mkdtempSync(path.join(require('os').tmpdir(), 'codex-list-'));
+            tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codex-list-'));
             sessionsDir = path.join(tmpDir, 'sessions');
             fs.mkdirSync(sessionsDir, { recursive: true });
             (adapter as any).codexSessionsDir = sessionsDir;