@ai-devkit/agent-manager 0.15.0 → 0.17.0

package/dist/utils/sortAgents.js

@@ -3,7 +3,7 @@ const STATUS_PRIORITY = {
     [AgentStatus.WAITING]: 0,
     [AgentStatus.RUNNING]: 1,
     [AgentStatus.IDLE]: 2,
-    [AgentStatus.UNKNOWN]: 3,
+    [AgentStatus.UNKNOWN]: 3
 };
 function compareByName(a, b) {
     return a.name.localeCompare(b.name);
@@ -11,25 +11,22 @@ function compareByName(a, b) {
 function compareByStatus(a, b) {
     const pa = STATUS_PRIORITY[a.status] ?? 999;
     const pb = STATUS_PRIORITY[b.status] ?? 999;
-    if (pa !== pb)
-        return pa - pb;
+    if (pa !== pb) return pa - pb;
     return compareByName(a, b);
 }
 function compareByPid(a, b) {
-    if (a.pid !== b.pid)
-        return a.pid - b.pid;
+    if (a.pid !== b.pid) return a.pid - b.pid;
     return compareByName(a, b);
 }
 function compareByLastActive(a, b) {
     const ta = a.lastActive instanceof Date ? a.lastActive.getTime() : new Date(a.lastActive).getTime();
     const tb = b.lastActive instanceof Date ? b.lastActive.getTime() : new Date(b.lastActive).getTime();
-    if (tb !== ta)
-        return tb - ta; // most recent first
+    if (tb !== ta) return tb - ta; // most recent first
     return compareByName(a, b);
 }
 export function sortAgents(agents, by) {
     const copy = agents.slice();
-    switch (by) {
+    switch(by){
         case 'name':
             copy.sort(compareByName);
             break;
@@ -45,4 +42,5 @@ export function sortAgents(agents, by) {
     }
     return copy;
 }
+
 //# sourceMappingURL=sortAgents.js.map

package/dist/utils/sortAgents.js.map

@@ -1 +1 @@
-{"version":3,"file":"sortAgents.js","sourceRoot":"","sources":["../../src/utils/sortAgents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAkB,MAAM,6BAA6B,CAAC;AAI1E,MAAM,eAAe,GAAgC;IACjD,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC;IACxB,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC;IACxB,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;IACrB,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC;CAC3B,CAAC;AAEF,SAAS,aAAa,CAAC,CAAY,EAAE,CAAY;IAC7C,OAAO,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AACxC,CAAC;AAED,SAAS,eAAe,CAAC,CAAY,EAAE,CAAY;IAC/C,MAAM,EAAE,GAAG,eAAe,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC;IAC5C,MAAM,EAAE,GAAG,eAAe,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC;IAC5C,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,EAAE,GAAG,EAAE,CAAC;IAC9B,OAAO,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAC/B,CAAC;AAED,SAAS,YAAY,CAAC,CAAY,EAAE,CAAY;IAC5C,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG;QAAE,OAAO,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC;IAC1C,OAAO,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAC/B,CAAC;AAED,SAAS,mBAAmB,CAAC,CAAY,EAAE,CAAY;IACnD,MAAM,EAAE,GAAG,CAAC,CAAC,UAAU,YAAY,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,OAAO,EAAE,CAAC;IACpG,MAAM,EAAE,GAAG,CAAC,CAAC,UAAU,YAAY,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,OAAO,EAAE,CAAC;IACpG,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,oBAAoB;IACnD,OAAO,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,MAAmB,EAAE,EAAgB;IAC5D,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC;IAC5B,QAAQ,EAAE,EAAE,CAAC;QACT,KAAK,MAAM;YACP,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;YACzB,MAAM;QACV,KAAK,QAAQ;YACT,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;YAC3B,MAAM;QACV,KAAK,KAAK;YACN,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YACxB,MAAM;QACV,KAAK,YAAY;YACb,IAAI,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;YAC/B,MAAM;IACd,CAAC;IACD,OAAO,IAAI,CAAC;AAChB,CAAC"}
+{"version":3,"sources":["../../src/utils/sortAgents.ts"],"sourcesContent":["import { AgentStatus, type AgentInfo } from '../adapters/AgentAdapter.js';\n\nexport type AgentSortKey = 'name' | 'status' | 'pid' | 'lastActive';\n\nconst STATUS_PRIORITY: Record<AgentStatus, number> = {\n    [AgentStatus.WAITING]: 0,\n    [AgentStatus.RUNNING]: 1,\n    [AgentStatus.IDLE]: 2,\n    [AgentStatus.UNKNOWN]: 3,\n};\n\nfunction compareByName(a: AgentInfo, b: AgentInfo): number {\n    return a.name.localeCompare(b.name);\n}\n\nfunction compareByStatus(a: AgentInfo, b: AgentInfo): number {\n    const pa = STATUS_PRIORITY[a.status] ?? 999;\n    const pb = STATUS_PRIORITY[b.status] ?? 999;\n    if (pa !== pb) return pa - pb;\n    return compareByName(a, b);\n}\n\nfunction compareByPid(a: AgentInfo, b: AgentInfo): number {\n    if (a.pid !== b.pid) return a.pid - b.pid;\n    return compareByName(a, b);\n}\n\nfunction compareByLastActive(a: AgentInfo, b: AgentInfo): number {\n    const ta = a.lastActive instanceof Date ? a.lastActive.getTime() : new Date(a.lastActive).getTime();\n    const tb = b.lastActive instanceof Date ? b.lastActive.getTime() : new Date(b.lastActive).getTime();\n    if (tb !== ta) return tb - ta; // most recent first\n    return compareByName(a, b);\n}\n\nexport function sortAgents(agents: AgentInfo[], by: AgentSortKey): AgentInfo[] {\n    const copy = agents.slice();\n    switch (by) {\n        case 'name':\n            copy.sort(compareByName);\n            break;\n        case 'status':\n            copy.sort(compareByStatus);\n            break;\n        case 'pid':\n            copy.sort(compareByPid);\n            break;\n        case 'lastActive':\n            copy.sort(compareByLastActive);\n            break;\n    }\n    return copy;\n}\n"],"names":["AgentStatus","STATUS_PRIORITY","WAITING","RUNNING","IDLE","UNKNOWN","compareByName","a","b","name","localeCompare","compareByStatus","pa","status","pb","compareByPid","pid","compareByLastActive","ta","lastActive","Date","getTime","tb","sortAgents","agents","by","copy","slice","sort"],"mappings":"AAAA,SAASA,WAAW,QAAwB,8BAA8B;AAI1E,MAAMC,kBAA+C;IACjD,CAACD,YAAYE,OAAO,CAAC,EAAE;IACvB,CAACF,YAAYG,OAAO,CAAC,EAAE;IACvB,CAACH,YAAYI,IAAI,CAAC,EAAE;IACpB,CAACJ,YAAYK,OAAO,CAAC,EAAE;AAC3B;AAEA,SAASC,cAAcC,CAAY,EAAEC,CAAY;IAC7C,OAAOD,EAAEE,IAAI,CAACC,aAAa,CAACF,EAAEC,IAAI;AACtC;AAEA,SAASE,gBAAgBJ,CAAY,EAAEC,CAAY;IAC/C,MAAMI,KAAKX,eAAe,CAACM,EAAEM,MAAM,CAAC,IAAI;IACxC,MAAMC,KAAKb,eAAe,CAACO,EAAEK,MAAM,CAAC,IAAI;IACxC,IAAID,OAAOE,IAAI,OAAOF,KAAKE;IAC3B,OAAOR,cAAcC,GAAGC;AAC5B;AAEA,SAASO,aAAaR,CAAY,EAAEC,CAAY;IAC5C,IAAID,EAAES,GAAG,KAAKR,EAAEQ,GAAG,EAAE,OAAOT,EAAES,GAAG,GAAGR,EAAEQ,GAAG;IACzC,OAAOV,cAAcC,GAAGC;AAC5B;AAEA,SAASS,oBAAoBV,CAAY,EAAEC,CAAY;IACnD,MAAMU,KAAKX,EAAEY,UAAU,YAAYC,OAAOb,EAAEY,UAAU,CAACE,OAAO,KAAK,IAAID,KAAKb,EAAEY,UAAU,EAAEE,OAAO;IACjG,MAAMC,KAAKd,EAAEW,UAAU,YAAYC,OAAOZ,EAAEW,UAAU,CAACE,OAAO,KAAK,IAAID,KAAKZ,EAAEW,UAAU,EAAEE,OAAO;IACjG,IAAIC,OAAOJ,IAAI,OAAOI,KAAKJ,IAAI,oBAAoB;IACnD,OAAOZ,cAAcC,GAAGC;AAC5B;AAEA,OAAO,SAASe,WAAWC,MAAmB,EAAEC,EAAgB;IAC5D,MAAMC,OAAOF,OAAOG,KAAK;IACzB,OAAQF;QACJ,KAAK;YACDC,KAAKE,IAAI,CAACtB;YACV;QACJ,KAAK;YACDoB,KAAKE,IAAI,CAACjB;YACV;QACJ,KAAK;YACDe,KAAKE,IAAI,CAACb;YACV;QACJ,KAAK;YACDW,KAAKE,IAAI,CAACX;YACV;IACR;IACA,OAAOS;AACX"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-devkit/agent-manager",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "type": "module",
   "description": "Standalone agent detection and management utilities for AI DevKit",
   "main": "dist/index.js",
@@ -12,7 +12,8 @@
     }
   },
   "scripts": {
-    "build": "tsc",
+    "build": "swc src -d dist --strip-leading-paths && tsc --emitDeclarationOnly",
+    "dev": "swc src -d dist --strip-leading-paths --watch",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
@@ -29,17 +30,20 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "better-sqlite3": "^12.6.2"
+    "better-sqlite3": "^12.6.2",
+    "uuid": "14.0.0"
   },
   "devDependencies": {
+    "@swc/cli": "^0.8.1",
+    "@swc/core": "^1.10.0",
     "@types/better-sqlite3": "^7.6.11",
     "@types/node": "^20.11.5",
-    "@typescript-eslint/eslint-plugin": "^6.19.1",
-    "@typescript-eslint/parser": "^6.19.1",
-    "@vitest/coverage-v8": "^2.1.0",
+    "@typescript-eslint/eslint-plugin": "^8.60.1",
+    "@typescript-eslint/parser": "^8.60.1",
+    "@vitest/coverage-v8": "^4.1.8",
     "eslint": "^8.56.0",
     "typescript": "^5.5.0",
-    "vitest": "^2.1.0"
+    "vitest": "^4.1.8"
   },
   "engines": {
     "node": ">=20.20.0"

package/src/AgentManager.ts

@@ -12,6 +12,7 @@ import type {
     ListSessionsOptions,
 } from './adapters/AgentAdapter.js';
 import { sortAgents, type AgentSortKey } from './utils/sortAgents.js';
+import { AgentRegistry, type RegistryEntry } from './utils/AgentRegistry.js';
 
 export interface ListAgentsOptions {
     /**
@@ -38,6 +39,11 @@ export interface ListAgentsOptions {
  */
 export class AgentManager {
     private adapters: Map<string, AgentAdapter> = new Map();
+    private registry: AgentRegistry;
+
+    constructor(registry: AgentRegistry = AgentRegistry.default()) {
+        this.registry = registry;
+    }
 
     /**
      * Register an adapter for a specific agent type
@@ -150,10 +156,37 @@ export class AgentManager {
             });
         }
 
+        const preExistingByPid = new Map(this.registry.list().map((e) => [e.pid, e]));
+        const entries = allAgents.map((agent) =>
+            this.toRegistryEntry(agent, preExistingByPid.get(agent.pid)),
+        );
+        if (entries.length > 0) this.registry.registerBatch(entries);
+        this.registry.prune();
+
+        for (const agent of allAgents) {
+            const entry = preExistingByPid.get(agent.pid);
+            if (entry) {
+                agent.name = entry.name;
+            }
+        }
+
         const sortKey: AgentSortKey = options?.sortBy ?? 'status';
         return sortAgents(allAgents, sortKey);
     }
 
+    private toRegistryEntry(agent: AgentInfo, existing?: RegistryEntry): RegistryEntry {
+        return {
+            name: existing?.name ?? agent.name,
+            type: agent.type,
+            pid: agent.pid,
+            tmuxSession: existing?.tmuxSession ?? '',
+            cwd: agent.projectPath,
+            startedAt: existing?.startedAt ?? new Date().toISOString(),
+            sessionId: agent.sessionId,
+            sessionFilePath: agent.sessionFilePath ?? '',
+        };
+    }
+
     /**
      * List historical sessions across every registered adapter.
      *
@@ -228,6 +261,13 @@ export class AgentManager {
     resolveAgent(input: string, agents: AgentInfo[]): AgentInfo | AgentInfo[] | null {
         if (!input || agents.length === 0) return null;
 
+        // Registry-first: if name is in registry and its PID is in the agent list, return it
+        const registryEntry = this.registry.lookup(input);
+        if (registryEntry) {
+            const registryAgent = agents.find((a) => a.pid === registryEntry.pid);
+            if (registryAgent) return registryAgent;
+        }
+
         const lowerInput = input.toLowerCase();
 
         // 1. Exact match (case-insensitive)

package/src/__tests__/AgentManager.test.ts

@@ -3,6 +3,9 @@
  */
 
 
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
 import { AgentManager } from '../AgentManager.js';
 import type {
     AgentAdapter,
@@ -12,6 +15,7 @@ import type {
     SessionSummary,
 } 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'));

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

@@ -427,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' }),
@@ -759,6 +758,7 @@ describe('ClaudeCodeAdapter', () => {
 
         beforeEach(() => {
             tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'claude-test-'));
+            (adapter as any).projectsDir = path.join(tmpDir, 'projects');
         });
 
         afterEach(() => {
@@ -1074,6 +1074,7 @@ describe('ClaudeCodeAdapter', () => {
 
         beforeEach(() => {
             tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'claude-test-'));
+            (adapter as any).projectsDir = path.join(tmpDir, 'projects');
         });
 
         afterEach(() => {

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

@@ -9,6 +9,7 @@ import * as path from 'path';
 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';
@@ -247,6 +248,204 @@ describe('CodexAdapter', () => {
 
             fs.rmSync(tmpDir, { recursive: true, force: true });
         });
+
+        it('should match resumed sessions by id even when the JSONL predates the process', async () => {
+            const sessionId = '019eabed-4079-7071-9531-b853ddd9914e';
+            const processes: ProcessInfo[] = [
+                {
+                    pid: 88018,
+                    command: `codex resume ${sessionId}`,
+                    cwd: '/repo-a',
+                    tty: 'ttys001',
+                    startTime: new Date('2026-06-10T12:00:00.000Z'),
+                },
+            ];
+            mockedListAgentProcesses.mockReturnValue(processes);
+            mockedEnrichProcesses.mockReturnValue(processes);
+
+            const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codex-resume-'));
+            const sessionsDir = path.join(tmpDir, 'sessions');
+            const dateDir = path.join(sessionsDir, '2026', '06', '09');
+            fs.mkdirSync(dateDir, { recursive: true });
+
+            const recentTs = new Date().toISOString();
+            const sessionFile = path.join(dateDir, `rollout-2026-06-09T12-28-33-${sessionId}.jsonl`);
+            fs.writeFileSync(sessionFile, [
+                JSON.stringify({ type: 'session_meta', payload: { id: sessionId, timestamp: recentTs, cwd: '/repo-a' } }),
+                JSON.stringify({ type: 'event', timestamp: recentTs, payload: { type: 'agent_message', message: 'resumed codex conversation' } }),
+            ].join('\n'));
+
+            (adapter as any).codexSessionsDir = sessionsDir;
+            mockedBatchGetSessionFileBirthtimes.mockReturnValue([]);
+
+            const agents = await adapter.detectAgents();
+
+            expect(mockedBatchGetSessionFileBirthtimes).not.toHaveBeenCalled();
+            expect(mockedMatchProcessesToSessions).not.toHaveBeenCalled();
+            expect(agents).toHaveLength(1);
+            expect(agents[0]).toMatchObject({
+                type: 'codex',
+                pid: 88018,
+                sessionId,
+                projectPath: '/repo-a',
+                sessionFilePath: sessionFile,
+            });
+            expect(agents[0].summary).toBe('resumed codex conversation');
+
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        });
+
+        it('should fall back to process-only when a resumed session becomes unreadable after direct matching', async () => {
+            const sessionId = '019eabed-4079-7071-9531-b853ddd9914e';
+            const processes: ProcessInfo[] = [
+                {
+                    pid: 88019,
+                    command: `codex resume ${sessionId}`,
+                    cwd: '/repo-a',
+                    tty: 'ttys001',
+                    startTime: new Date('2026-06-10T12:00:00.000Z'),
+                },
+            ];
+            mockedListAgentProcesses.mockReturnValue(processes);
+            mockedEnrichProcesses.mockReturnValue(processes);
+
+            const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codex-resume-gone-'));
+            const sessionsDir = path.join(tmpDir, 'sessions');
+            const dateDir = path.join(sessionsDir, '2026', '06', '09');
+            fs.mkdirSync(dateDir, { recursive: true });
+
+            const sessionFile = path.join(dateDir, `rollout-2026-06-09T12-28-33-${sessionId}.jsonl`);
+
+            (adapter as any).codexSessionsDir = sessionsDir;
+            const findSpy = vi.spyOn(adapter as any, 'findSessionFileById').mockReturnValue({
+                sessionId,
+                filePath: sessionFile,
+                projectDir: dateDir,
+                birthtimeMs: Date.now(),
+                resolvedCwd: '/repo-a',
+            });
+            mockedBatchGetSessionFileBirthtimes.mockReturnValue([]);
+
+            try {
+                const agents = await adapter.detectAgents();
+
+                expect(agents).toHaveLength(1);
+                expect(agents[0]).toMatchObject({
+                    type: 'codex',
+                    pid: 88019,
+                    sessionId: 'pid-88019',
+                    projectPath: '/repo-a',
+                });
+                expect(agents[0].sessionFilePath).toBeUndefined();
+            } finally {
+                findSpy.mockRestore();
+                fs.rmSync(tmpDir, { recursive: true, force: true });
+            }
+        });
+    });
+
+    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', () => {