@ai-devkit/agent-manager 0.1.0 → 0.3.0

package/dist/terminal/TtyWriter.d.ts

@@ -0,0 +1,23 @@
+import type { TerminalLocation } from './TerminalFocusManager';
+export declare class TtyWriter {
+    /**
+     * Send a message as keyboard input to a terminal session.
+     *
+     * Dispatches to the correct mechanism based on terminal type:
+     * - tmux: `tmux send-keys`
+     * - iTerm2: AppleScript `write text`
+     * - Terminal.app: System Events `keystroke` + `key code 36` (Return)
+     *
+     * All AppleScript is executed via `execFile('osascript', ['-e', script])`
+     * to avoid shell interpolation and command injection.
+     *
+     * @param location Terminal location from TerminalFocusManager.findTerminal()
+     * @param message Text to send
+     * @throws Error if terminal type is unsupported or send fails
+     */
+    static send(location: TerminalLocation, message: string): Promise<void>;
+    private static sendViaTmux;
+    private static sendViaITerm2;
+    private static sendViaTerminalApp;
+}
+//# sourceMappingURL=TtyWriter.d.ts.map

package/dist/terminal/TtyWriter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TtyWriter.d.ts","sourceRoot":"","sources":["../../src/terminal/TtyWriter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAa/D,qBAAa,SAAS;IAClB;;;;;;;;;;;;;;OAcG;WACU,IAAI,CAAC,QAAQ,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;mBAgBxD,WAAW;mBAIX,aAAa;mBAuBb,kBAAkB;CAqC1C"}

package/dist/terminal/TtyWriter.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TtyWriter = void 0;
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const TerminalFocusManager_1 = require("./TerminalFocusManager");
+const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
+/**
+ * Escape a string for safe use inside an AppleScript double-quoted string.
+ * Backslashes and double quotes must be escaped.
+ */
+function escapeAppleScript(text) {
+    return text.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+class TtyWriter {
+    /**
+     * Send a message as keyboard input to a terminal session.
+     *
+     * Dispatches to the correct mechanism based on terminal type:
+     * - tmux: `tmux send-keys`
+     * - iTerm2: AppleScript `write text`
+     * - Terminal.app: System Events `keystroke` + `key code 36` (Return)
+     *
+     * All AppleScript is executed via `execFile('osascript', ['-e', script])`
+     * to avoid shell interpolation and command injection.
+     *
+     * @param location Terminal location from TerminalFocusManager.findTerminal()
+     * @param message Text to send
+     * @throws Error if terminal type is unsupported or send fails
+     */
+    static async send(location, message) {
+        switch (location.type) {
+            case TerminalFocusManager_1.TerminalType.TMUX:
+                return TtyWriter.sendViaTmux(location.identifier, message);
+            case TerminalFocusManager_1.TerminalType.ITERM2:
+                return TtyWriter.sendViaITerm2(location.tty, message);
+            case TerminalFocusManager_1.TerminalType.TERMINAL_APP:
+                return TtyWriter.sendViaTerminalApp(location.tty, message);
+            default:
+                throw new Error(`Cannot send input: unsupported terminal type "${location.type}". ` +
+                    'Supported: tmux, iTerm2, Terminal.app.');
+        }
+    }
+    static async sendViaTmux(identifier, message) {
+        await execFileAsync('tmux', ['send-keys', '-t', identifier, message, 'Enter']);
+    }
+    static async sendViaITerm2(tty, message) {
+        const escaped = escapeAppleScript(message);
+        const script = `
+tell application "iTerm"
+  repeat with w in windows
+    repeat with t in tabs of w
+      repeat with s in sessions of t
+        if tty of s is "${tty}" then
+          tell s to write text "${escaped}"
+          return "ok"
+        end if
+      end repeat
+    end repeat
+  end repeat
+end tell
+return "not_found"`;
+        const { stdout } = await execFileAsync('osascript', ['-e', script]);
+        if (stdout.trim() !== 'ok') {
+            throw new Error(`iTerm2 session not found for TTY ${tty}`);
+        }
+    }
+    static async sendViaTerminalApp(tty, message) {
+        const escaped = escapeAppleScript(message);
+        // Use System Events keystroke to type into the foreground process,
+        // NOT Terminal.app's "do script" which runs a new shell command.
+        // First activate Terminal and select the correct tab, then type via System Events.
+        const script = `
+tell application "Terminal"
+  set targetFound to false
+  repeat with w in windows
+    repeat with i from 1 to count of tabs of w
+      set t to tab i of w
+      if tty of t is "${tty}" then
+        set selected tab of w to t
+        set index of w to 1
+        activate
+        set targetFound to true
+        exit repeat
+      end if
+    end repeat
+    if targetFound then exit repeat
+  end repeat
+  if not targetFound then return "not_found"
+end tell
+delay 0.1
+tell application "System Events"
+  tell process "Terminal"
+    keystroke "${escaped}"
+    key code 36
+  end tell
+end tell
+return "ok"`;
+        const { stdout } = await execFileAsync('osascript', ['-e', script]);
+        if (stdout.trim() !== 'ok') {
+            throw new Error(`Terminal.app tab not found for TTY ${tty}`);
+        }
+    }
+}
+exports.TtyWriter = TtyWriter;
+//# sourceMappingURL=TtyWriter.js.map

package/dist/terminal/TtyWriter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TtyWriter.js","sourceRoot":"","sources":["../../src/terminal/TtyWriter.ts"],"names":[],"mappings":";;;AAAA,iDAAyC;AACzC,+BAAiC;AAEjC,iEAAsD;AAEtD,MAAM,aAAa,GAAG,IAAA,gBAAS,EAAC,wBAAQ,CAAC,CAAC;AAE1C;;;GAGG;AACH,SAAS,iBAAiB,CAAC,IAAY;IACnC,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AAC5D,CAAC;AAED,MAAa,SAAS;IAClB;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,QAA0B,EAAE,OAAe;QACzD,QAAQ,QAAQ,CAAC,IAAI,EAAE,CAAC;YACpB,KAAK,mCAAY,CAAC,IAAI;gBAClB,OAAO,SAAS,CAAC,WAAW,CAAC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;YAC/D,KAAK,mCAAY,CAAC,MAAM;gBACpB,OAAO,SAAS,CAAC,aAAa,CAAC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;YAC1D,KAAK,mCAAY,CAAC,YAAY;gBAC1B,OAAO,SAAS,CAAC,kBAAkB,CAAC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;YAC/D;gBACI,MAAM,IAAI,KAAK,CACX,iDAAiD,QAAQ,CAAC,IAAI,KAAK;oBACnE,wCAAwC,CAC3C,CAAC;QACV,CAAC;IACL,CAAC;IAEO,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,UAAkB,EAAE,OAAe;QAChE,MAAM,aAAa,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;IACnF,CAAC;IAEO,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,GAAW,EAAE,OAAe;QAC3D,MAAM,OAAO,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC;QAC3C,MAAM,MAAM,GAAG;;;;;0BAKG,GAAG;kCACK,OAAO;;;;;;;mBAOtB,CAAC;QAEZ,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;QACpE,IAAI,MAAM,CAAC,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,oCAAoC,GAAG,EAAE,CAAC,CAAC;QAC/D,CAAC;IACL,CAAC;IAEO,MAAM,CAAC,KAAK,CAAC,kBAAkB,CAAC,GAAW,EAAE,OAAe;QAChE,MAAM,OAAO,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC;QAC3C,mEAAmE;QACnE,iEAAiE;QACjE,mFAAmF;QACnF,MAAM,MAAM,GAAG;;;;;;wBAMC,GAAG;;;;;;;;;;;;;;;iBAeV,OAAO;;;;YAIZ,CAAC;QAEL,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;QACpE,IAAI,MAAM,CAAC,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,sCAAsC,GAAG,EAAE,CAAC,CAAC;QACjE,CAAC;IACL,CAAC;CACJ;AAhGD,8BAgGC"}

package/dist/terminal/index.d.ts

@@ -1,3 +1,5 @@
 export { TerminalFocusManager } from './TerminalFocusManager';
+export { TerminalType } from './TerminalFocusManager';
 export type { TerminalLocation } from './TerminalFocusManager';
+export { TtyWriter } from './TtyWriter';
 //# sourceMappingURL=index.d.ts.map

package/dist/terminal/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/terminal/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/terminal/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/dist/terminal/index.js

@@ -1,6 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TerminalFocusManager = void 0;
+exports.TtyWriter = exports.TerminalType = exports.TerminalFocusManager = void 0;
 var TerminalFocusManager_1 = require("./TerminalFocusManager");
 Object.defineProperty(exports, "TerminalFocusManager", { enumerable: true, get: function () { return TerminalFocusManager_1.TerminalFocusManager; } });
+var TerminalFocusManager_2 = require("./TerminalFocusManager");
+Object.defineProperty(exports, "TerminalType", { enumerable: true, get: function () { return TerminalFocusManager_2.TerminalType; } });
+var TtyWriter_1 = require("./TtyWriter");
+Object.defineProperty(exports, "TtyWriter", { enumerable: true, get: function () { return TtyWriter_1.TtyWriter; } });
 //# sourceMappingURL=index.js.map

package/dist/terminal/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/terminal/index.ts"],"names":[],"mappings":";;;AAAA,+DAA8D;AAArD,4HAAA,oBAAoB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/terminal/index.ts"],"names":[],"mappings":";;;AAAA,+DAA8D;AAArD,4HAAA,oBAAoB,OAAA;AAC7B,+DAAsD;AAA7C,oHAAA,YAAY,OAAA;AAErB,yCAAwC;AAA/B,sGAAA,SAAS,OAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-devkit/agent-manager",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Standalone agent detection and management utilities for AI DevKit",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

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

@@ -127,7 +127,7 @@ describe('ClaudeCodeAdapter', () => {
             expect(agents[0].summary).toContain('Investigate failing tests in package');
         });
 
-        it('should return empty list when process cwd has no matching session', async () => {
+        it('should include process-only entry when process cwd has no matching session', async () => {
             mockedListProcesses.mockReturnValue([
                 {
                     pid: 777,
@@ -148,7 +148,125 @@ describe('ClaudeCodeAdapter', () => {
             jest.spyOn(adapter as unknown as AdapterPrivates, 'readHistory').mockReturnValue([]);
 
             const agents = await adapter.detectAgents();
-            expect(agents).toEqual([]);
+            expect(agents).toHaveLength(1);
+            expect(agents[0]).toMatchObject({
+                type: 'claude',
+                status: AgentStatus.RUNNING,
+                pid: 777,
+                projectPath: '/project/without-session',
+                sessionId: 'pid-777',
+                summary: 'Claude process running',
+            });
+        });
+
+        it('should match process in subdirectory to project-root session', async () => {
+            mockedListProcesses.mockReturnValue([
+                {
+                    pid: 888,
+                    command: 'claude',
+                    cwd: '/Users/test/my-project/packages/cli',
+                    tty: 'ttys009',
+                },
+            ]);
+            jest.spyOn(adapter as unknown as AdapterPrivates, 'readSessions').mockReturnValue([
+                {
+                    sessionId: 'session-3',
+                    projectPath: '/Users/test/my-project',
+                    sessionLogPath: '/mock/path/session-3.jsonl',
+                    slug: 'gentle-otter',
+                    lastEntry: { type: 'assistant' },
+                    lastActive: new Date(),
+                },
+            ]);
+            jest.spyOn(adapter as unknown as AdapterPrivates, 'readHistory').mockReturnValue([
+                {
+                    display: 'Refactor CLI command flow',
+                    timestamp: Date.now(),
+                    project: '/Users/test/my-project',
+                    sessionId: 'session-3',
+                },
+            ]);
+
+            const agents = await adapter.detectAgents();
+            expect(agents).toHaveLength(1);
+            expect(agents[0]).toMatchObject({
+                type: 'claude',
+                pid: 888,
+                sessionId: 'session-3',
+                projectPath: '/Users/test/my-project',
+                summary: 'Refactor CLI command flow',
+            });
+        });
+
+        it('should use latest history entry for process-only fallback session id', async () => {
+            mockedListProcesses.mockReturnValue([
+                {
+                    pid: 97529,
+                    command: 'claude',
+                    cwd: '/Users/test/my-project/packages/cli',
+                    tty: 'ttys021',
+                },
+            ]);
+            jest.spyOn(adapter as unknown as AdapterPrivates, 'readSessions').mockReturnValue([]);
+            jest.spyOn(adapter as unknown as AdapterPrivates, 'readHistory').mockReturnValue([
+                {
+                    display: '/status',
+                    timestamp: 1772122701536,
+                    project: '/Users/test/my-project/packages/cli',
+                    sessionId: '69237415-b0c3-4990-ba53-15882616509e',
+                },
+            ]);
+
+            const agents = await adapter.detectAgents();
+            expect(agents).toHaveLength(1);
+            expect(agents[0]).toMatchObject({
+                type: 'claude',
+                pid: 97529,
+                projectPath: '/Users/test/my-project/packages/cli',
+                sessionId: '69237415-b0c3-4990-ba53-15882616509e',
+                summary: '/status',
+                status: AgentStatus.RUNNING,
+            });
+            expect(agents[0].lastActive.toISOString()).toBe('2026-02-26T16:18:21.536Z');
+        });
+
+        it('should prefer exact-cwd history session over parent-project session match', async () => {
+            mockedListProcesses.mockReturnValue([
+                {
+                    pid: 97529,
+                    command: 'claude',
+                    cwd: '/Users/test/my-project/packages/cli',
+                    tty: 'ttys021',
+                },
+            ]);
+            jest.spyOn(adapter as unknown as AdapterPrivates, 'readSessions').mockReturnValue([
+                {
+                    sessionId: 'old-parent-session',
+                    projectPath: '/Users/test/my-project',
+                    sessionLogPath: '/mock/path/old-parent-session.jsonl',
+                    slug: 'fluffy-brewing-kazoo',
+                    lastEntry: { type: 'assistant' },
+                    lastActive: new Date('2026-02-23T17:24:50.996Z'),
+                },
+            ]);
+            jest.spyOn(adapter as unknown as AdapterPrivates, 'readHistory').mockReturnValue([
+                {
+                    display: '/status',
+                    timestamp: 1772122701536,
+                    project: '/Users/test/my-project/packages/cli',
+                    sessionId: '69237415-b0c3-4990-ba53-15882616509e',
+                },
+            ]);
+
+            const agents = await adapter.detectAgents();
+            expect(agents).toHaveLength(1);
+            expect(agents[0]).toMatchObject({
+                type: 'claude',
+                pid: 97529,
+                sessionId: '69237415-b0c3-4990-ba53-15882616509e',
+                projectPath: '/Users/test/my-project/packages/cli',
+                summary: '/status',
+            });
         });
     });
 

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

@@ -0,0 +1,319 @@
+import { beforeEach, describe, expect, it, jest } from '@jest/globals';
+import { CodexAdapter } from '../../adapters/CodexAdapter';
+import type { ProcessInfo } from '../../adapters/AgentAdapter';
+import { AgentStatus } from '../../adapters/AgentAdapter';
+import { listProcesses } from '../../utils/process';
+
+jest.mock('../../utils/process', () => ({
+    listProcesses: jest.fn(),
+}));
+
+const mockedListProcesses = listProcesses as jest.MockedFunction<typeof listProcesses>;
+
+interface MockSession {
+    sessionId: string;
+    projectPath: string;
+    summary: string;
+    sessionStart?: Date;
+    lastActive: Date;
+    lastPayloadType?: string;
+}
+
+describe('CodexAdapter', () => {
+    let adapter: CodexAdapter;
+
+    beforeEach(() => {
+        adapter = new CodexAdapter();
+        mockedListProcesses.mockReset();
+    });
+
+    it('should expose codex type', () => {
+        expect(adapter.type).toBe('codex');
+    });
+
+    it('should match codex commands in canHandle', () => {
+        expect(
+            adapter.canHandle({
+                pid: 1,
+                command: 'codex',
+                cwd: '/repo',
+                tty: 'ttys001',
+            }),
+        ).toBe(true);
+
+        expect(
+            adapter.canHandle({
+                pid: 2,
+                command: '/usr/local/bin/CODEX --sandbox workspace-write',
+                cwd: '/repo',
+                tty: 'ttys002',
+            }),
+        ).toBe(true);
+
+        expect(
+            adapter.canHandle({
+                pid: 4,
+                command: 'node /worktrees/feature-codex-adapter-agent-manager-package/node_modules/nx/src/daemon/server/start.js',
+                cwd: '/repo',
+                tty: 'ttys004',
+            }),
+        ).toBe(false);
+
+        expect(
+            adapter.canHandle({
+                pid: 3,
+                command: 'node app.js',
+                cwd: '/repo',
+                tty: 'ttys003',
+            }),
+        ).toBe(false);
+    });
+
+    it('should return empty list when no codex process is running', async () => {
+        mockedListProcesses.mockReturnValue([]);
+
+        const agents = await adapter.detectAgents();
+        expect(agents).toEqual([]);
+    });
+
+    it('should map active codex sessions to matching processes by cwd', async () => {
+        mockedListProcesses.mockReturnValue([
+            { pid: 100, command: 'codex', cwd: '/repo-a', tty: 'ttys001' },
+        ] as ProcessInfo[]);
+
+        jest.spyOn(adapter as any, 'readSessions').mockReturnValue([
+            {
+                sessionId: 'abc12345-session',
+                projectPath: '/repo-a',
+                summary: 'Implement adapter flow',
+                sessionStart: new Date('2026-02-26T15:00:00.000Z'),
+                lastActive: new Date(),
+                lastPayloadType: 'token_count',
+            } as MockSession,
+        ]);
+
+        const agents = await adapter.detectAgents();
+        expect(agents).toHaveLength(1);
+        expect(agents[0]).toMatchObject({
+            name: 'repo-a',
+            type: 'codex',
+            status: AgentStatus.RUNNING,
+            summary: 'Implement adapter flow',
+            pid: 100,
+            projectPath: '/repo-a',
+            sessionId: 'abc12345-session',
+        });
+    });
+
+    it('should still map sessions with task_complete as waiting when process is running', async () => {
+        mockedListProcesses.mockReturnValue([
+            { pid: 101, command: 'codex', cwd: '/repo-b', tty: 'ttys001' },
+        ] as ProcessInfo[]);
+
+        jest.spyOn(adapter as any, 'readSessions').mockReturnValue([
+            {
+                sessionId: 'ended-1111',
+                projectPath: '/repo-b',
+                summary: 'Ended turn but process still alive',
+                sessionStart: new Date('2026-02-26T15:00:00.000Z'),
+                lastActive: new Date(),
+                lastPayloadType: 'task_complete',
+            } as MockSession,
+        ]);
+
+        const agents = await adapter.detectAgents();
+        expect(agents).toHaveLength(1);
+        expect(agents[0].sessionId).toBe('ended-1111');
+        expect(agents[0].status).toBe(AgentStatus.WAITING);
+    });
+
+    it('should use codex-session-id-prefix fallback name when cwd is missing', async () => {
+        mockedListProcesses.mockReturnValue([
+            { pid: 102, command: 'codex', cwd: '', tty: 'ttys009' },
+        ] as ProcessInfo[]);
+
+        jest.spyOn(adapter as any, 'readSessions').mockReturnValue([
+            {
+                sessionId: 'abcdef123456',
+                projectPath: '',
+                summary: 'No cwd available',
+                sessionStart: new Date('2026-02-26T15:00:00.000Z'),
+                lastActive: new Date(),
+                lastPayloadType: 'agent_reasoning',
+            } as MockSession,
+        ]);
+
+        const agents = await adapter.detectAgents();
+        expect(agents).toHaveLength(1);
+        expect(agents[0].name).toBe('codex-abcdef12');
+    });
+
+    it('should report waiting status for recent agent_message events', async () => {
+        mockedListProcesses.mockReturnValue([
+            { pid: 103, command: 'codex', cwd: '/repo-c', tty: 'ttys010' },
+        ] as ProcessInfo[]);
+
+        jest.spyOn(adapter as any, 'readSessions').mockReturnValue([
+            {
+                sessionId: 'waiting-1234',
+                projectPath: '/repo-c',
+                summary: 'Waiting',
+                sessionStart: new Date('2026-02-26T15:00:00.000Z'),
+                lastActive: new Date(),
+                lastPayloadType: 'agent_message',
+            } as MockSession,
+        ]);
+
+        const agents = await adapter.detectAgents();
+        expect(agents).toHaveLength(1);
+        expect(agents[0].status).toBe(AgentStatus.WAITING);
+    });
+
+    it('should report idle status when session exceeds shared threshold', async () => {
+        mockedListProcesses.mockReturnValue([
+            { pid: 104, command: 'codex', cwd: '/repo-d', tty: 'ttys011' },
+        ] as ProcessInfo[]);
+
+        jest.spyOn(adapter as any, 'readSessions').mockReturnValue([
+            {
+                sessionId: 'idle-5678',
+                projectPath: '/repo-d',
+                summary: 'Idle',
+                sessionStart: new Date('2026-02-26T15:00:00.000Z'),
+                lastActive: new Date(Date.now() - 10 * 60 * 1000),
+                lastPayloadType: 'token_count',
+            } as MockSession,
+        ]);
+
+        const agents = await adapter.detectAgents();
+        expect(agents).toHaveLength(1);
+        expect(agents[0].status).toBe(AgentStatus.IDLE);
+    });
+
+    it('should list unmatched running codex process even when no session matches', async () => {
+        mockedListProcesses.mockReturnValue([
+            { pid: 105, command: 'codex', cwd: '/repo-x', tty: 'ttys012' },
+        ] as ProcessInfo[]);
+
+        jest.spyOn(adapter as any, 'readSessions').mockReturnValue([
+            {
+                sessionId: 'other-session',
+                projectPath: '/repo-y',
+                summary: 'Other repo',
+                sessionStart: new Date('2026-02-26T15:00:00.000Z'),
+                lastActive: new Date(),
+                lastPayloadType: 'agent_message',
+            } as MockSession,
+        ]);
+
+        const agents = await adapter.detectAgents();
+        expect(agents).toHaveLength(1);
+        expect(agents[0].pid).toBe(105);
+    });
+
+    it('should list process when session metadata is unavailable', async () => {
+        mockedListProcesses.mockReturnValue([
+            { pid: 106, command: 'codex', cwd: '/repo-z', tty: 'ttys013' },
+        ] as ProcessInfo[]);
+        jest.spyOn(adapter as any, 'readSessions').mockReturnValue([]);
+
+        const agents = await adapter.detectAgents();
+        expect(agents).toHaveLength(1);
+        expect(agents[0].pid).toBe(106);
+        expect(agents[0].summary).toContain('No Codex session metadata');
+    });
+
+    it('should choose same-cwd session closest to process start time', async () => {
+        mockedListProcesses.mockReturnValue([
+            { pid: 107, command: 'codex', cwd: '/repo-time', tty: 'ttys014' },
+        ] as ProcessInfo[]);
+
+        jest.spyOn(adapter as any, 'readSessions').mockReturnValue([
+            {
+                sessionId: 'far-session',
+                projectPath: '/repo-time',
+                summary: 'Far start time',
+                sessionStart: new Date('2026-02-26T14:00:00.000Z'),
+                lastActive: new Date('2026-02-26T15:10:00.000Z'),
+                lastPayloadType: 'agent_message',
+            } as MockSession,
+            {
+                sessionId: 'near-session',
+                projectPath: '/repo-time',
+                summary: 'Near start time',
+                sessionStart: new Date('2026-02-26T15:00:20.000Z'),
+                lastActive: new Date('2026-02-26T15:11:00.000Z'),
+                lastPayloadType: 'agent_message',
+            } as MockSession,
+        ]);
+        jest.spyOn(adapter as any, 'getProcessStartTimes').mockReturnValue(
+            new Map([[107, new Date('2026-02-26T15:00:00.000Z')]]),
+        );
+
+        const agents = await adapter.detectAgents();
+        expect(agents).toHaveLength(1);
+        expect(agents[0].sessionId).toBe('near-session');
+    });
+
+    it('should prefer missing-cwd session before any-session fallback for unmatched process', async () => {
+        mockedListProcesses.mockReturnValue([
+            { pid: 108, command: 'codex', cwd: '/repo-missing-cwd', tty: 'ttys015' },
+        ] as ProcessInfo[]);
+
+        jest.spyOn(adapter as any, 'readSessions').mockReturnValue([
+            {
+                sessionId: 'any-session',
+                projectPath: '/another-repo',
+                summary: 'Any session fallback',
+                sessionStart: new Date('2026-02-26T15:00:00.000Z'),
+                lastActive: new Date('2026-02-26T15:12:00.000Z'),
+                lastPayloadType: 'agent_message',
+            } as MockSession,
+            {
+                sessionId: 'missing-cwd-session',
+                projectPath: '',
+                summary: 'Missing cwd session',
+                sessionStart: new Date('2026-02-26T15:00:10.000Z'),
+                lastActive: new Date('2026-02-26T15:11:00.000Z'),
+                lastPayloadType: 'agent_message',
+            } as MockSession,
+        ]);
+        jest.spyOn(adapter as any, 'getProcessStartTimes').mockReturnValue(
+            new Map([[108, new Date('2026-02-26T15:00:00.000Z')]]),
+        );
+
+        const agents = await adapter.detectAgents();
+        expect(agents).toHaveLength(1);
+        expect(agents[0].sessionId).toBe('missing-cwd-session');
+    });
+
+    it('should not reuse the same session for multiple running processes', async () => {
+        mockedListProcesses.mockReturnValue([
+            { pid: 109, command: 'codex', cwd: '/repo-shared', tty: 'ttys016' },
+            { pid: 110, command: 'codex', cwd: '/repo-shared', tty: 'ttys017' },
+        ] as ProcessInfo[]);
+
+        jest.spyOn(adapter as any, 'readSessions').mockReturnValue([
+            {
+                sessionId: 'shared-session',
+                projectPath: '/repo-shared',
+                summary: 'Only one session exists',
+                sessionStart: new Date('2026-02-26T15:00:00.000Z'),
+                lastActive: new Date('2026-02-26T15:11:00.000Z'),
+                lastPayloadType: 'agent_message',
+            } as MockSession,
+        ]);
+        jest.spyOn(adapter as any, 'getProcessStartTimes').mockReturnValue(
+            new Map([
+                [109, new Date('2026-02-26T15:00:00.000Z')],
+                [110, new Date('2026-02-26T15:00:30.000Z')],
+            ]),
+        );
+
+        const agents = await adapter.detectAgents();
+        expect(agents).toHaveLength(2);
+        const mappedAgents = agents.filter((agent) => agent.sessionId === 'shared-session');
+        expect(mappedAgents).toHaveLength(1);
+        expect(agents.some((agent) => agent.sessionId.startsWith('pid-'))).toBe(true);
+    });
+});