fix(agent-manager): prefer exact history cwd for claude pid-session mapping

Author: codeaholicguy

docs/ai/design/feature-agent-management.md

@@ -119,6 +119,7 @@ const STATUS_CONFIG = {
 interface ClaudeCodeSession {
   sessionId: string;        // UUID from session filename
   projectPath: string;      // Original project path (from sessions-index.json)
+  lastCwd?: string;         // Last cwd seen in session entries (when available)
   slug: string;             // Human-readable name (e.g., "merry-wobbling-starlight")
   sessionLogPath: string;   // Path to the .jsonl session file
   debugLogPath?: string;    // Path to the debug log file
@@ -147,12 +148,13 @@ interface HistoryEntry {
 1. **Process Detection**: Query running processes (`ps aux | grep claude`) → List of PIDs + TTYs
 2. **Session Discovery**: Read `~/.claude/projects/*/sessions-index.json` → List of sessions with project paths
 3. **Session-Process Correlation**: 
-   - Group running processes by CWD (project path)
-   - Group available sessions by project path
-   - **Duplicate Filtering**: If multiple sessions match a project path:
-     - Sort sessions by last active time (newest first)
-     - Take the top N sessions, where N is the number of active processes for that path
-     - Strictly map active processes to these N sessions to avoid "ghost" agents
+   - Running Claude processes are source-of-truth for membership
+   - Correlation priority for each process:
+     - **Phase 1 (`cwd`)**: Exact match with session `lastCwd` or `projectPath`
+     - **Phase 2 (`history-cwd`)**: Exact match with `history.jsonl` where `history.project === process.cwd`
+     - **Phase 3 (`project-parent`)**: Process cwd is child of session `projectPath` or `lastCwd`
+     - **Phase 4 (`process-only`)**: Emit process-only agent when no session match exists
+   - This prevents dropped Claude processes when transcripts lag or when process cwd is a subdirectory (e.g. `packages/cli`)
 4. **Terminal Location**: For each matched process, find terminal location:
    - Get TTY from PID: `ps -p {PID} -o tty=`
    - Query tmux: `tmux list-panes -a -F '#{pane_tty} #{session}:#{window}.#{pane}'`
@@ -164,6 +166,7 @@ interface HistoryEntry {
    - `progress` or `thinking` → running
    - `system` or old timestamp → idle
 6. **Summary Extraction**: Read `~/.claude/history.jsonl` → Get last user prompt for each session
+   - For history-cwd fallback and process-only fallback, history entry also provides `sessionId` and `lastActive`
 7. **Agent Naming**: 
    - Use project basename (e.g., "ai-devkit")
    - If `slug` exists in session, use for disambiguation (e.g., "ai-devkit (merry)")

packages/agent-manager/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',
+            });
         });
     });