@ai-devkit/agent-manager 0.10.0 → 0.11.0

package/dist/utils/session.js

@@ -2,8 +2,8 @@
 /**
  * Session File Utilities
  *
- * Shell command wrappers for discovering session files and their birth times.
- * Uses `stat` to get exact epoch-second birth timestamps without reading file contents.
+ * Utilities for discovering session files and their birth times.
+ * Uses Node.js fs APIs to get birth timestamps without reading file contents.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -39,62 +39,108 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isDirectory = isDirectory;
+exports.safeStat = safeStat;
+exports.safeReadFile = safeReadFile;
+exports.safeReaddir = safeReaddir;
+exports.listJsonl = listJsonl;
 exports.batchGetSessionFileBirthtimes = batchGetSessionFileBirthtimes;
+const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
-const child_process_1 = require("child_process");
 /**
- * Get birth times for .jsonl session files across multiple directories in a single shell call.
- *
- * Combines all directory globs into one `stat` command to avoid per-directory exec overhead.
- * Returns empty array if no directories have .jsonl files or command fails.
- * resolvedCwd is left empty — the adapter must set it.
+ * Check whether a path exists and is a directory.
+ * Returns false on any error (missing path, permission denied, broken symlink, etc.).
  */
-function batchGetSessionFileBirthtimes(dirs) {
-    if (dirs.length === 0)
-        return [];
+function isDirectory(p) {
+    return safeStat(p)?.isDirectory() ?? false;
+}
+/**
+ * `fs.statSync` that swallows errors and returns `undefined` on failure.
+ * Callers can pull whichever fields they need (mtime, birthtime, ...).
+ */
+function safeStat(filePath) {
     try {
-        const isMacOS = process.platform === 'darwin';
-        const globs = dirs.map((d) => `"${d}"/*.jsonl`).join(' ');
-        // || true prevents non-zero exit when some globs have no .jsonl matches
-        const command = isMacOS
-            ? `stat -f '%B %N' ${globs} 2>/dev/null || true`
-            : `stat --format='%W %n' ${globs} 2>/dev/null || true`;
-        const output = (0, child_process_1.execSync)(command, { encoding: 'utf-8' });
-        return parseStatOutput(output);
+        return fs.statSync(filePath);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * `fs.readFileSync` (utf-8) that swallows errors and returns `undefined`
+ * on failure. Use when an unreadable file should be skipped rather than
+ * raised.
+ */
+function safeReadFile(filePath) {
+    try {
+        return fs.readFileSync(filePath, 'utf-8');
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * `fs.readdirSync` that swallows errors and returns `[]` on failure.
+ * Useful when walking optional/transient directories where missing or
+ * unreadable entries should be skipped silently.
+ */
+function safeReaddir(dir) {
+    try {
+        return fs.readdirSync(dir);
     }
     catch {
         return [];
     }
 }
 /**
- * Parse stat output lines into SessionFile entries.
+ * List entries in a directory that end with `.jsonl`. Returns `[]` on
+ * read errors. The result preserves directory order (no sorting).
+ */
+function listJsonl(dir) {
+    return safeReaddir(dir).filter((name) => name.endsWith('.jsonl'));
+}
+/**
+ * Get birth times for .jsonl session files across multiple directories.
+ *
+ * Enumerates each directory with readdirSync and stats each .jsonl file
+ * to get its birth time. No shell commands are used.
+ * Returns empty array if no directories have .jsonl files or reads fail.
+ * resolvedCwd is left empty — the adapter must set it.
  */
-function parseStatOutput(output) {
+function batchGetSessionFileBirthtimes(dirs) {
+    if (dirs.length === 0)
+        return [];
     const results = [];
-    for (const rawLine of output.trim().split('\n')) {
-        const line = rawLine.trim();
-        if (!line)
-            continue;
-        // Format: "<epoch_seconds> <filepath>"
-        const spaceIdx = line.indexOf(' ');
-        if (spaceIdx === -1)
-            continue;
-        const epochStr = line.slice(0, spaceIdx);
-        const filePath = line.slice(spaceIdx + 1).trim();
-        const epochSeconds = parseInt(epochStr, 10);
-        if (!Number.isFinite(epochSeconds) || epochSeconds <= 0)
-            continue;
-        const fileName = path.basename(filePath);
-        if (!fileName.endsWith('.jsonl'))
+    for (const dir of dirs) {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir);
+        }
+        catch {
             continue;
-        const sessionId = fileName.replace(/\.jsonl$/, '');
-        results.push({
-            sessionId,
-            filePath,
-            projectDir: path.dirname(filePath),
-            birthtimeMs: epochSeconds * 1000,
-            resolvedCwd: '',
-        });
+        }
+        for (const entry of entries) {
+            if (!entry.endsWith('.jsonl'))
+                continue;
+            const filePath = path.join(dir, entry);
+            let birthtimeMs;
+            try {
+                birthtimeMs = fs.statSync(filePath).birthtimeMs;
+            }
+            catch {
+                continue;
+            }
+            if (!Number.isFinite(birthtimeMs) || birthtimeMs <= 0)
+                continue;
+            const sessionId = entry.replace(/\.jsonl$/, '');
+            results.push({
+                sessionId,
+                filePath,
+                projectDir: dir,
+                birthtimeMs,
+                resolvedCwd: '',
+            });
+        }
     }
     return results;
 }

package/dist/utils/session.js.map

@@ -1 +1 @@
-{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/utils/session.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCH,sEAiBC;AA/CD,2CAA6B;AAC7B,iDAAyC;AAsBzC;;;;;;GAMG;AACH,SAAgB,6BAA6B,CAAC,IAAc;IACxD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEjC,IAAI,CAAC;QACD,MAAM,OAAO,GAAG,OAAO,CAAC,QAAQ,KAAK,QAAQ,CAAC;QAC9C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC1D,wEAAwE;QACxE,MAAM,OAAO,GAAG,OAAO;YACnB,CAAC,CAAC,mBAAmB,KAAK,sBAAsB;YAChD,CAAC,CAAC,yBAAyB,KAAK,sBAAsB,CAAC;QAE3D,MAAM,MAAM,GAAG,IAAA,wBAAQ,EAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC;QAExD,OAAO,eAAe,CAAC,MAAM,CAAC,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,EAAE,CAAC;IACd,CAAC;AACL,CAAC;AAED;;GAEG;AACH,SAAS,eAAe,CAAC,MAAc;IACnC,MAAM,OAAO,GAAkB,EAAE,CAAC;IAElC,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,CAAC,IAAI;YAAE,SAAS;QAEpB,uCAAuC;QACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,QAAQ,KAAK,CAAC,CAAC;YAAE,SAAS;QAE9B,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;QACzC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAEjD,MAAM,YAAY,GAAG,QAAQ,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QAC5C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,YAAY,IAAI,CAAC;YAAE,SAAS;QAElE,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACzC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC;YAAE,SAAS;QAE3C,MAAM,SAAS,GAAG,QAAQ,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;QAEnD,OAAO,CAAC,IAAI,CAAC;YACT,SAAS;YACT,QAAQ;YACR,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC;YAClC,WAAW,EAAE,YAAY,GAAG,IAAI;YAChC,WAAW,EAAE,EAAE;SAClB,CAAC,CAAC;IACP,CAAC;IAED,OAAO,OAAO,CAAC;AACnB,CAAC"}
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/utils/session.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BH,kCAEC;AAMD,4BAMC;AAOD,oCAMC;AAOD,kCAMC;AAMD,8BAEC;AAUD,sEAwCC;AA7HD,uCAAyB;AACzB,2CAA6B;AAsB7B;;;GAGG;AACH,SAAgB,WAAW,CAAC,CAAS;IACjC,OAAO,QAAQ,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,KAAK,CAAC;AAC/C,CAAC;AAED;;;GAGG;AACH,SAAgB,QAAQ,CAAC,QAAgB;IACrC,IAAI,CAAC;QACD,OAAO,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,SAAS,CAAC;IACrB,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,SAAgB,YAAY,CAAC,QAAgB;IACzC,IAAI,CAAC;QACD,OAAO,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,SAAS,CAAC;IACrB,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,SAAgB,WAAW,CAAC,GAAW;IACnC,IAAI,CAAC;QACD,OAAO,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,EAAE,CAAC;IACd,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,SAAgB,SAAS,CAAC,GAAW;IACjC,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;AACtE,CAAC;AAED;;;;;;;GAOG;AACH,SAAgB,6BAA6B,CAAC,IAAc;IACxD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEjC,MAAM,OAAO,GAAkB,EAAE,CAAC;IAElC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACrB,IAAI,OAAiB,CAAC;QACtB,IAAI,CAAC;YACD,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QAClC,CAAC;QAAC,MAAM,CAAC;YACL,SAAS;QACb,CAAC;QAED,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC1B,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC;gBAAE,SAAS;YAExC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YAEvC,IAAI,WAAmB,CAAC;YACxB,IAAI,CAAC;gBACD,WAAW,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,WAAW,CAAC;YACpD,CAAC;YAAC,MAAM,CAAC;gBACL,SAAS;YACb,CAAC;YAED,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,WAAW,IAAI,CAAC;gBAAE,SAAS;YAEhE,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;YAEhD,OAAO,CAAC,IAAI,CAAC;gBACT,SAAS;gBACT,QAAQ;gBACR,UAAU,EAAE,GAAG;gBACf,WAAW;gBACX,WAAW,EAAE,EAAE;aAClB,CAAC,CAAC;QACP,CAAC;IACL,CAAC;IAED,OAAO,OAAO,CAAC;AACnB,CAAC"}

package/package.json

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

package/src/AgentManager.ts

@@ -5,7 +5,12 @@
  * Manages adapter registration and aggregates results from all adapters.
  */
 
-import type { AgentAdapter, AgentInfo } from './adapters/AgentAdapter';
+import type {
+    AgentAdapter,
+    AgentInfo,
+    SessionSummary,
+    ListSessionsOptions,
+} from './adapters/AgentAdapter';
 import { AgentStatus } from './adapters/AgentAdapter';
 
 /**
@@ -141,12 +146,59 @@ export class AgentManager {
         return this.sortAgentsByStatus(allAgents);
     }
 
+    /**
+     * List historical sessions across every registered adapter.
+     *
+     * When `opts.type` is set, adapters whose `type` doesn't match are
+     * skipped without being called. The remaining adapters' results are
+     * merged and sorted by `lastActive` descending. Adapter failures are
+     * caught (one-line stderr warning) so one broken adapter doesn't hide
+     * the others.
+     *
+     * @param opts Filter options computed by the CLI; the manager passes
+     *   them through to each adapter unchanged.
+     */
+    async listSessions(opts?: ListSessionsOptions): Promise<SessionSummary[]> {
+        const targetAdapters = Array.from(this.adapters.values()).filter(
+            (adapter) => opts?.type === undefined || adapter.type === opts.type,
+        );
+
+        const errors: Array<{ type: string; error: Error }> = [];
+
+        const results = await Promise.all(
+            targetAdapters.map(async (adapter) => {
+                try {
+                    return await adapter.listSessions(opts);
+                } catch (error) {
+                    const err = error instanceof Error ? error : new Error(String(error));
+                    errors.push({ type: adapter.type, error: err });
+                    return [];
+                }
+            }),
+        );
+
+        if (errors.length > 0) {
+            console.error(`Warning: ${errors.length} adapter(s) failed to list sessions:`);
+            for (const { type, error } of errors) {
+                console.error(`  - ${type}: ${error.message}`);
+            }
+        }
+
+        const merged: SessionSummary[] = [];
+        for (const list of results) {
+            merged.push(...list);
+        }
+
+        merged.sort((a, b) => b.lastActive.getTime() - a.lastActive.getTime());
+        return merged;
+    }
+
     /**
      * Sort agents by status priority
-     * 
+     *
      * Priority order: waiting > running > idle > unknown
      * This ensures agents that need attention appear first.
-     * 
+     *
      * @param agents Array of agents to sort
      * @returns Sorted array of agents
      */

package/src/__tests__/AgentManager.test.ts

@@ -4,15 +4,25 @@
 
 import { describe, it, expect, beforeEach } from '@jest/globals';
 import { AgentManager } from '../AgentManager';
-import type { AgentAdapter, AgentInfo, AgentType, ConversationMessage } from '../adapters/AgentAdapter';
+import type {
+    AgentAdapter,
+    AgentInfo,
+    AgentType,
+    ConversationMessage,
+    SessionSummary,
+} from '../adapters/AgentAdapter';
 import { AgentStatus } from '../adapters/AgentAdapter';
 
 // Mock adapter for testing
 class MockAdapter implements AgentAdapter {
+    public lastListSessionsOpts: unknown = undefined;
+
     constructor(
         public readonly type: AgentType,
         private mockAgents: AgentInfo[] = [],
-        private shouldFail: boolean = false
+        private shouldFail: boolean = false,
+        private mockSessions: SessionSummary[] = [],
+        private shouldFailListSessions: boolean = false,
     ) { }
 
     async detectAgents(): Promise<AgentInfo[]> {
@@ -30,6 +40,14 @@ class MockAdapter implements AgentAdapter {
         return [];
     }
 
+    async listSessions(opts?: unknown): Promise<SessionSummary[]> {
+        this.lastListSessionsOpts = opts;
+        if (this.shouldFailListSessions) {
+            throw new Error(`Mock adapter ${this.type} listSessions failed`);
+        }
+        return this.mockSessions;
+    }
+
     setAgents(agents: AgentInfo[]): void {
         this.mockAgents = agents;
     }
@@ -37,6 +55,14 @@ class MockAdapter implements AgentAdapter {
     setFail(shouldFail: boolean): void {
         this.shouldFail = shouldFail;
     }
+
+    setSessions(sessions: SessionSummary[]): void {
+        this.mockSessions = sessions;
+    }
+
+    setFailListSessions(shouldFail: boolean): void {
+        this.shouldFailListSessions = shouldFail;
+    }
 }
 
 // Helper to create mock agent
@@ -226,6 +252,112 @@ describe('AgentManager', () => {
         });
     });
 
+    describe('listSessions', () => {
+        function createMockSession(overrides: Partial<SessionSummary> = {}): SessionSummary {
+            return {
+                type: 'claude',
+                sessionId: 'session-1',
+                cwd: '/repo',
+                firstUserMessage: 'hello',
+                lastActive: new Date('2025-01-01T00:00:00Z'),
+                startedAt: new Date('2025-01-01T00:00:00Z'),
+                sessionFilePath: '/tmp/session-1.jsonl',
+                ...overrides,
+            };
+        }
+
+        it('returns empty array when no adapters are registered', async () => {
+            const result = await manager.listSessions();
+            expect(result).toEqual([]);
+        });
+
+        it('merges sessions from every registered adapter', async () => {
+            const claudeSession = createMockSession({ type: 'claude', sessionId: 'c1' });
+            const codexSession = createMockSession({ type: 'codex', sessionId: 'cx1' });
+            manager.registerAdapter(new MockAdapter('claude', [], false, [claudeSession]));
+            manager.registerAdapter(new MockAdapter('codex', [], false, [codexSession]));
+
+            const result = await manager.listSessions();
+
+            expect(result).toHaveLength(2);
+            expect(result.map((s) => s.sessionId).sort()).toEqual(['c1', 'cx1']);
+        });
+
+        it('sorts merged sessions by lastActive descending', async () => {
+            const older = createMockSession({
+                sessionId: 'older',
+                lastActive: new Date('2025-01-01T00:00:00Z'),
+            });
+            const newer = createMockSession({
+                type: 'codex',
+                sessionId: 'newer',
+                lastActive: new Date('2025-06-01T00:00:00Z'),
+            });
+            manager.registerAdapter(new MockAdapter('claude', [], false, [older]));
+            manager.registerAdapter(new MockAdapter('codex', [], false, [newer]));
+
+            const result = await manager.listSessions();
+
+            expect(result.map((s) => s.sessionId)).toEqual(['newer', 'older']);
+        });
+
+        it('skips adapters whose type does not match opts.type', async () => {
+            const claudeAdapter = new MockAdapter(
+                'claude',
+                [],
+                false,
+                [createMockSession({ type: 'claude', sessionId: 'c1' })],
+            );
+            const codexAdapter = new MockAdapter(
+                'codex',
+                [],
+                false,
+                [createMockSession({ type: 'codex', sessionId: 'cx1' })],
+            );
+            manager.registerAdapter(claudeAdapter);
+            manager.registerAdapter(codexAdapter);
+
+            const result = await manager.listSessions({ type: 'claude' });
+
+            expect(result).toHaveLength(1);
+            expect(result[0].sessionId).toBe('c1');
+            // Codex adapter must not have been called
+            expect(codexAdapter.lastListSessionsOpts).toBeUndefined();
+            expect(claudeAdapter.lastListSessionsOpts).toEqual({ type: 'claude' });
+        });
+
+        it('tolerates an adapter that throws and still returns the others', async () => {
+            const goodSession = createMockSession({ sessionId: 'good' });
+            manager.registerAdapter(new MockAdapter('claude', [], false, [goodSession]));
+            manager.registerAdapter(
+                new MockAdapter('codex', [], false, [], true /* failListSessions */),
+            );
+
+            const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => undefined);
+
+            try {
+                const result = await manager.listSessions();
+                expect(result).toHaveLength(1);
+                expect(result[0].sessionId).toBe('good');
+                expect(consoleErrorSpy).toHaveBeenCalled();
+            } finally {
+                consoleErrorSpy.mockRestore();
+            }
+        });
+
+        it('passes the same opts to every called adapter', async () => {
+            const a = new MockAdapter('claude', [], false, []);
+            const b = new MockAdapter('codex', [], false, []);
+            manager.registerAdapter(a);
+            manager.registerAdapter(b);
+
+            await manager.listSessions({ cwd: '/Users/test/proj' });
+
+            expect(a.lastListSessionsOpts).toEqual({ cwd: '/Users/test/proj' });
+            expect(b.lastListSessionsOpts).toEqual({ cwd: '/Users/test/proj' });
+        });
+    });
+
     describe('resolveAgent', () => {
         it('should return null for empty input or empty agents list', () => {
             const agent = createMockAgent({ name: 'test-agent' });

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

@@ -18,9 +18,13 @@ jest.mock('../../utils/process', () => ({
     enrichProcesses: jest.fn(),
 }));
 
-jest.mock('../../utils/session', () => ({
-    batchGetSessionFileBirthtimes: jest.fn(),
-}));
+jest.mock('../../utils/session', () => {
+    const actual = jest.requireActual('../../utils/session') as typeof import('../../utils/session');
+    return {
+        ...actual,
+        batchGetSessionFileBirthtimes: jest.fn(),
+    };
+});
 
 jest.mock('../../utils/matching', () => ({
     matchProcessesToSessions: jest.fn(),
@@ -1288,4 +1292,156 @@ describe('ClaudeCodeAdapter', () => {
             expect(messages[0].content).toBe('Real question');
         });
     });
+
+    describe('listSessions', () => {
+        let tmpDir: string;
+        let projectsDir: string;
+
+        beforeEach(() => {
+            tmpDir = fs.mkdtempSync(path.join(require('os').tmpdir(), 'claude-list-'));
+            projectsDir = path.join(tmpDir, 'projects');
+            fs.mkdirSync(projectsDir, { recursive: true });
+            (adapter as any).projectsDir = projectsDir;
+        });
+
+        afterEach(() => {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        });
+
+        function writeSession(projectDir: string, sessionId: string, lines: object[]): string {
+            fs.mkdirSync(projectDir, { recursive: true });
+            const filePath = path.join(projectDir, `${sessionId}.jsonl`);
+            fs.writeFileSync(filePath, lines.map((l) => JSON.stringify(l)).join('\n'));
+            return filePath;
+        }
+
+        it('returns empty when projects dir does not exist', async () => {
+            fs.rmSync(projectsDir, { recursive: true, force: true });
+            const result = await adapter.listSessions();
+            expect(result).toEqual([]);
+        });
+
+        it('returns sessions from a single cwd-scoped project dir', async () => {
+            const cwd = '/Users/test/proj';
+            const projDir = path.join(projectsDir, '-Users-test-proj');
+            const filePath = writeSession(projDir, 'sess-1', [
+                { type: 'user', timestamp: '2025-01-01T00:00:00Z', cwd, message: { content: 'first prompt' } },
+                { type: 'assistant', timestamp: '2025-01-01T00:01:00Z' },
+            ]);
+
+            const result = await adapter.listSessions({ cwd });
+
+            expect(result).toHaveLength(1);
+            expect(result[0]).toMatchObject({
+                type: 'claude',
+                sessionId: 'sess-1',
+                cwd,
+                firstUserMessage: 'first prompt',
+                sessionFilePath: filePath,
+            });
+            expect(result[0].lastActive).toBeInstanceOf(Date);
+            expect(result[0].startedAt).toBeInstanceOf(Date);
+        });
+
+        it('lists sessions from all project dirs when no cwd filter', async () => {
+            const cwdA = '/Users/test/proj-a';
+            const cwdB = '/Users/test/proj-b';
+            writeSession(path.join(projectsDir, '-Users-test-proj-a'), 'a', [
+                { type: 'user', timestamp: '2025-01-01T00:00:00Z', cwd: cwdA, message: { content: 'msg-a' } },
+            ]);
+            writeSession(path.join(projectsDir, '-Users-test-proj-b'), 'b', [
+                { type: 'user', timestamp: '2025-01-02T00:00:00Z', cwd: cwdB, message: { content: 'msg-b' } },
+            ]);
+
+            const result = await adapter.listSessions();
+
+            expect(result).toHaveLength(2);
+            expect(result.map((r) => r.sessionId).sort()).toEqual(['a', 'b']);
+            const cwds = result.map((r) => r.cwd).sort();
+            expect(cwds).toEqual([cwdA, cwdB]);
+        });
+
+        it('drops sessions whose recorded cwd does not match opts.cwd (strict equality)', async () => {
+            const cwdReal = '/Users/test/foo';
+            const cwdRequested = '/Users/test/foo/sub';
+            writeSession(path.join(projectsDir, '-Users-test-foo'), 's', [
+                { type: 'user', timestamp: '2025-01-01T00:00:00Z', cwd: cwdReal, message: { content: 'hi' } },
+            ]);
+
+            // Encoded dir for the requested cwd doesn't exist → return []
+            const result = await adapter.listSessions({ cwd: cwdRequested });
+            expect(result).toEqual([]);
+        });
+
+        it('drops sessions whose recorded cwd disagrees with the encoded dir', async () => {
+            // Edge case: encoded dir lookup matches, but session content
+            // records a different cwd. Strict-equality filter must reject.
+            const requested = '/Users/test/proj';
+            const projDir = path.join(projectsDir, '-Users-test-proj');
+            writeSession(projDir, 's', [
+                { type: 'user', timestamp: '2025-01-01T00:00:00Z', cwd: '/different/path', message: { content: 'mismatch' } },
+            ]);
+
+            const result = await adapter.listSessions({ cwd: requested });
+            expect(result).toEqual([]);
+        });
+
+        it('finds sessions whose recorded cwd lives in a different encoded dir (worktree case)', async () => {
+            // Real-world case: Claude Code is launched in /repo, then chdirs into
+            // /repo/.worktrees/feature. The session file is stored under the
+            // ENCODED launch dir, but its content records the worktree path.
+            // listSessions({ cwd: worktree }) must still find it.
+            const launchDir = path.join(projectsDir, '-repo');
+            const worktreeCwd = '/repo/.worktrees/feature';
+            writeSession(launchDir, 'wt', [
+                { type: 'user', timestamp: '2025-01-01T00:00:00Z', cwd: worktreeCwd, message: { content: 'in worktree' } },
+            ]);
+
+            const result = await adapter.listSessions({ cwd: worktreeCwd });
+            expect(result).toHaveLength(1);
+            expect(result[0]).toMatchObject({
+                sessionId: 'wt',
+                cwd: worktreeCwd,
+                firstUserMessage: 'in worktree',
+            });
+        });
+
+        it('skips malformed session files', async () => {
+            const cwd = '/Users/test/p';
+            const projDir = path.join(projectsDir, '-Users-test-p');
+            fs.mkdirSync(projDir, { recursive: true });
+            fs.writeFileSync(path.join(projDir, 'bad.jsonl'), 'not valid json');
+            writeSession(projDir, 'good', [
+                { type: 'user', timestamp: '2025-01-01T00:00:00Z', cwd, message: { content: 'ok' } },
+            ]);
+
+            const result = await adapter.listSessions({ cwd });
+            expect(result).toHaveLength(1);
+            expect(result[0].sessionId).toBe('good');
+        });
+
+        it('captures first user message after filtering noise', async () => {
+            const cwd = '/Users/test/q';
+            writeSession(path.join(projectsDir, '-Users-test-q'), 's', [
+                { type: 'user', timestamp: '2025-01-01T00:00:00Z', cwd, message: { content: 'Tool loaded.' } },
+                { type: 'user', timestamp: '2025-01-01T00:00:01Z', cwd, message: { content: 'real first prompt' } },
+                { type: 'user', timestamp: '2025-01-01T00:00:02Z', cwd, message: { content: 'second prompt' } },
+            ]);
+
+            const result = await adapter.listSessions({ cwd });
+            expect(result).toHaveLength(1);
+            expect(result[0].firstUserMessage).toBe('real first prompt');
+        });
+
+        it('returns empty firstUserMessage when no user message exists', async () => {
+            const cwd = '/Users/test/empty';
+            writeSession(path.join(projectsDir, '-Users-test-empty'), 's', [
+                { type: 'assistant', timestamp: '2025-01-01T00:00:00Z' },
+            ]);
+
+            const result = await adapter.listSessions({ cwd });
+            expect(result).toHaveLength(1);
+            expect(result[0].firstUserMessage).toBe('');
+        });
+    });
 });