@ai-devkit/agent-manager 0.28.1 → 0.30.0

package/src/__tests__/print/ClaudePrintAgentService.test.ts

@@ -18,7 +18,7 @@ describe('ClaudePrintAgentService', () => {
 
     it('runs first and resumed sends and records provider identity/results', async () => {
         const api = await import('../../index.js') as Record<string, unknown>;
-        const base = { id: 'id', name: 'reviewer', providerSessionId: 'session', sessionHealth: 'uninitialized' };
+        const base = { id: 'id', name: 'reviewer', provider: 'claude', providerSessionId: 'session', sessionHealth: 'uninitialized' };
         const repository = {
             resolve: vi.fn().mockResolvedValue(base),
             acquireRun: vi.fn()
@@ -43,4 +43,36 @@ describe('ClaudePrintAgentService', () => {
             status: 'succeeded', exitCode: 0, sessionHealth: 'healthy',
         }));
     });
+
+    it('rejects a non-Claude target without acquiring or mutating it', async () => {
+        const api = await import('../../index.js') as Record<string, unknown>;
+        const Service = api.ClaudePrintAgentService as new (options: unknown) => any;
+        const target = { id: 'id', name: 'reviewer', provider: 'pi' };
+        const repository = {
+            resolve: vi.fn().mockResolvedValue(target),
+            acquireRun: vi.fn(), recordProviderProcess: vi.fn(), completeRun: vi.fn(),
+        };
+
+        await expect(new Service({ repository, probe: { validate: vi.fn() }, runner: { run: vi.fn() } })
+            .send('reviewer', 'x')).rejects.toMatchObject({ code: 'CLAUDE_PRINT_UNSUPPORTED' });
+        expect(repository.acquireRun).not.toHaveBeenCalled();
+        expect(repository.completeRun).not.toHaveBeenCalled();
+    });
+
+    it('does not turn a successful completion write failure into a second completion', async () => {
+        const api = await import('../../index.js') as Record<string, unknown>;
+        const Service = api.ClaudePrintAgentService as new (options: unknown) => any;
+        const target = { id: 'id', name: 'reviewer', provider: 'claude', providerSessionId: 'session', sessionHealth: 'healthy' };
+        const completionFailure = new Error('completion failed');
+        const repository = {
+            resolve: vi.fn().mockResolvedValue(target),
+            acquireRun: vi.fn().mockResolvedValue({ agent: target, token: 'one' }),
+            recordProviderProcess: vi.fn(), completeRun: vi.fn().mockRejectedValue(completionFailure),
+        };
+        const runner = { run: vi.fn().mockResolvedValue({ sessionId: 'session', result: 'answer', exitCode: 0 }) };
+
+        await expect(new Service({ repository, probe: { validate: vi.fn() }, runner })
+            .send('reviewer', 'x')).rejects.toBe(completionFailure);
+        expect(repository.completeRun).toHaveBeenCalledOnce();
+    });
 });

package/src/__tests__/print/ClaudePrintRunner.test.ts

@@ -2,6 +2,7 @@ import { EventEmitter } from 'node:events';
 import { PassThrough, Writable } from 'node:stream';
 import { describe, expect, it, vi } from 'vitest';
 import type { DurableAgent } from '../../index.js';
+import { ClaudePrintRunner } from '../../providers/claude/durable/ClaudePrintRunner.js';
 
 function agent(): DurableAgent {
     return {
@@ -34,15 +35,12 @@ function fakeSpawn(events: object[], exitCode = 0) {
 
 describe('ClaudePrintRunner', () => {
     it('starts a caller-assigned session and persists provider identity before stdin', async () => {
-        const api = await import('../../index.js') as Record<string, unknown>;
-        expect(api).toHaveProperty('ClaudePrintRunner');
         const fixture = fakeSpawn([
             { type: 'system', subtype: 'init', session_id: agent().providerSessionId },
             { type: 'result', session_id: agent().providerSessionId, result: 'done' },
         ]);
         let persisted = false;
-        const Runner = api.ClaudePrintRunner as new (options: unknown) => any;
-        const runner = new Runner({ spawn: fixture.spawn, processInspector: {
+        const runner = new ClaudePrintRunner({ spawn: fixture.spawn, processInspector: {
             getIdentity: () => ({ pid: 4242, startedAt: 'provider-start' }),
         } });
 
@@ -63,10 +61,8 @@ describe('ClaudePrintRunner', () => {
     });
 
     it('uses exact resume and rejects a mismatched result session', async () => {
-        const api = await import('../../index.js') as Record<string, unknown>;
         const fixture = fakeSpawn([{ type: 'result', session_id: 'wrong', result: 'nope' }]);
-        const Runner = api.ClaudePrintRunner as new (options: unknown) => any;
-        const runner = new Runner({ spawn: fixture.spawn, processInspector: {
+        const runner = new ClaudePrintRunner({ spawn: fixture.spawn, processInspector: {
             getIdentity: () => ({ pid: 4242, startedAt: 'provider-start' }),
         } });
 
@@ -79,10 +75,8 @@ describe('ClaudePrintRunner', () => {
     });
 
     it('does not disclose provider stderr in a failed-run error', async () => {
-        const api = await import('../../index.js') as Record<string, unknown>;
         const fixture = fakeSpawn([], 1);
-        const Runner = api.ClaudePrintRunner as new (options: unknown) => any;
-        const runner = new Runner({ spawn: fixture.spawn, processInspector: {
+        const runner = new ClaudePrintRunner({ spawn: fixture.spawn, processInspector: {
             getIdentity: () => ({ pid: 4242, startedAt: 'provider-start' }),
         } });
         fixture.spawn.mockImplementationOnce((...args: unknown[]) => {

package/src/__tests__/providers/claude/ClaudeAgentMapper.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from 'vitest';
+
+import { AgentStatus, type ProcessInfo } from '../../../adapters/AgentAdapter.js';
+import { ClaudeAgentMapper } from '../../../providers/claude/ClaudeAgentMapper.js';
+import type { ClaudeSession } from '../../../providers/claude/ClaudeSessionParser.js';
+import type { SessionFile } from '../../../utils/session.js';
+
+function makeProcess(overrides: Partial<ProcessInfo> = {}): ProcessInfo {
+    return {
+        pid: 123,
+        command: 'claude',
+        cwd: '/repo/my-app',
+        tty: 'ttys001',
+        ...overrides,
+    };
+}
+
+function makeSession(overrides: Partial<ClaudeSession> = {}): ClaudeSession {
+    return {
+        sessionId: 'session-1',
+        projectPath: '/repo/my-app',
+        sessionStart: new Date('2026-08-23T10:00:00.000Z'),
+        lastActive: new Date('2026-08-23T10:05:00.000Z'),
+        lastEntryType: 'assistant',
+        isInterrupted: false,
+        lastUserMessage: 'Review this change',
+        ...overrides,
+    };
+}
+
+function makeSessionFile(overrides: Partial<SessionFile> = {}): SessionFile {
+    return {
+        sessionId: 'session-1',
+        filePath: '/home/.claude/projects/-repo-my-app/session-1.jsonl',
+        projectDir: '/home/.claude/projects/-repo-my-app',
+        birthtimeMs: new Date('2026-08-23T10:00:00.000Z').getTime(),
+        resolvedCwd: '/repo/my-app',
+        ...overrides,
+    };
+}
+
+describe('ClaudeAgentMapper', () => {
+    it('prefers live PID-file status and waiting reason over JSONL-derived status', () => {
+        const mapper = new ClaudeAgentMapper();
+
+        const agent = mapper.mapSessionToAgent({
+            session: makeSession({ lastEntryType: 'assistant' }),
+            processInfo: makeProcess(),
+            sessionFile: makeSessionFile(),
+            liveInfo: {
+                pidStatus: AgentStatus.WAITING,
+                waitingFor: 'approve Read',
+            },
+        });
+
+        expect(agent).toMatchObject({
+            name: 'my-app-123',
+            type: 'claude',
+            status: AgentStatus.WAITING,
+            summary: 'Review this change — waiting for approve Read',
+            pid: 123,
+            projectPath: '/repo/my-app',
+            sessionId: 'session-1',
+            sessionFilePath: '/home/.claude/projects/-repo-my-app/session-1.jsonl',
+        });
+    });
+
+    it('maps unmatched processes to the existing process-only fallback shape', () => {
+        const mapper = new ClaudeAgentMapper();
+
+        const agent = mapper.mapProcessOnlyAgent(makeProcess({ pid: 456, cwd: '/repo/tooling' }));
+
+        expect(agent).toMatchObject({
+            name: 'tooling-456',
+            type: 'claude',
+            status: AgentStatus.IDLE,
+            summary: 'Unknown',
+            pid: 456,
+            projectPath: '/repo/tooling',
+            sessionId: 'pid-456',
+        });
+        expect(agent.lastActive).toBeInstanceOf(Date);
+    });
+});

package/src/__tests__/providers/claude/ClaudeSessionLocator.test.ts

@@ -0,0 +1,411 @@
+import type { MockedFunction } from 'vitest';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { AgentStatus, type ProcessInfo } from '../../../adapters/AgentAdapter.js';
+import { ClaudeSessionLocator } from '../../../providers/claude/ClaudeSessionLocator.js';
+import { batchGetSessionFileBirthtimes } from '../../../utils/session.js';
+import type { SessionFile } from '../../../utils/session.js';
+
+vi.mock('../../../utils/session.js', async (importOriginal) => {
+    const actual = await importOriginal() as typeof import('../../../utils/session.js');
+    return {
+        ...actual,
+        batchGetSessionFileBirthtimes: vi.fn(),
+    };
+});
+
+const mockedBatchGetSessionFileBirthtimes =
+    batchGetSessionFileBirthtimes as MockedFunction<typeof batchGetSessionFileBirthtimes>;
+
+const tmpDirs: string[] = [];
+
+function makeTmpDir(): string {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'claude-locator-test-'));
+    tmpDirs.push(dir);
+    return dir;
+}
+
+function makeProcess(overrides: Partial<ProcessInfo> = {}): ProcessInfo {
+    return {
+        pid: 123,
+        command: 'claude',
+        cwd: '/repo/my-app',
+        tty: 'ttys001',
+        startTime: new Date('2026-08-23T10:00:00.000Z'),
+        ...overrides,
+    };
+}
+
+type PidFileMatching = (processes: ProcessInfo[]) => {
+    direct: Array<{ process: ProcessInfo; sessionFile: SessionFile }>;
+    fallback: ProcessInfo[];
+};
+
+/** `tryPidFileMatching` is private; tests drive it directly like the sibling adapter suites do. */
+function bindPidFileMatching(locator: ClaudeSessionLocator): PidFileMatching {
+    return (locator as unknown as { tryPidFileMatching: PidFileMatching })
+        .tryPidFileMatching.bind(locator) as PidFileMatching;
+}
+
+/** `getProjectDir` is private; bound here so the encoding tests read cleanly. */
+function bindProjectDir(locator: ClaudeSessionLocator): (cwd: string) => string {
+    return (locator as unknown as { getProjectDir: (cwd: string) => string })
+        .getProjectDir.bind(locator);
+}
+
+describe('ClaudeSessionLocator', () => {
+    beforeEach(() => {
+        mockedBatchGetSessionFileBirthtimes.mockReset();
+    });
+
+    afterEach(() => {
+        for (const dir of tmpDirs.splice(0)) {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+
+    it('matches resumed sessions directly and carries live PID status metadata', () => {
+        const root = makeTmpDir();
+        const projectsDir = path.join(root, 'projects');
+        const sessionsDir = path.join(root, 'sessions');
+        const cwd = '/repo/my-app';
+        const sessionId = '12345678-1234-1234-1234-123456789abc';
+        const projectDir = path.join(projectsDir, '-repo-my-app');
+        const sessionFile = path.join(projectDir, `${sessionId}.jsonl`);
+        fs.mkdirSync(projectDir, { recursive: true });
+        fs.mkdirSync(sessionsDir, { recursive: true });
+        fs.writeFileSync(sessionFile, '{}\n');
+        fs.writeFileSync(path.join(sessionsDir, '123.json'), JSON.stringify({
+            pid: 123,
+            sessionId,
+            cwd,
+            startedAt: new Date('2026-08-23T10:00:00.000Z').getTime(),
+            kind: 'interactive',
+            entrypoint: 'cli',
+            status: 'waiting',
+            waitingFor: 'approve Read',
+        }));
+
+        const locator = new ClaudeSessionLocator({ projectsDir, sessionsDir });
+        const matches = locator.matchRunningProcesses([
+            makeProcess({ command: `claude --resume ${sessionId}`, cwd }),
+        ]);
+
+        expect(matches.direct).toHaveLength(1);
+        expect(matches.legacyMatches).toEqual([]);
+        expect(matches.direct[0]).toMatchObject({
+            pidStatus: AgentStatus.WAITING,
+            waitingFor: 'approve Read',
+            sessionFile: {
+                sessionId,
+                filePath: sessionFile,
+                projectDir,
+                resolvedCwd: cwd,
+            },
+        });
+    });
+    describe('discoverLiveSessions', () => {
+        let tmpDir: string;
+        let projectsDir: string;
+        let locator: ClaudeSessionLocator;
+
+        beforeEach(() => {
+            tmpDir = makeTmpDir();
+            projectsDir = path.join(tmpDir, 'projects');
+            locator = new ClaudeSessionLocator({
+                projectsDir,
+                sessionsDir: path.join(tmpDir, 'sessions'),
+            });
+        });
+
+        it('should return empty when projects dir does not exist', () => {
+            const missing = new ClaudeSessionLocator({
+                projectsDir: path.join(tmpDir, 'nonexistent'),
+                sessionsDir: path.join(tmpDir, 'sessions'),
+            });
+
+            const result = missing.discoverLiveSessions([
+                { pid: 1, command: 'claude', cwd: '/test', tty: '' },
+            ]);
+            expect(result).toEqual([]);
+        });
+
+        it('should scan only directories matching process CWDs', () => {
+            // /my/project → -my-project (encoded dir)
+            const encodedDir = path.join(projectsDir, '-my-project');
+            fs.mkdirSync(encodedDir, { recursive: true });
+
+            // Also create another dir that should NOT be scanned
+            const otherDir = path.join(projectsDir, '-other-project');
+            fs.mkdirSync(otherDir, { recursive: true });
+
+            const mockFiles: SessionFile[] = [
+                {
+                    sessionId: 's1',
+                    filePath: path.join(encodedDir, 's1.jsonl'),
+                    projectDir: encodedDir,
+                    birthtimeMs: 1710800324000,
+                    resolvedCwd: '',
+                },
+            ];
+            mockedBatchGetSessionFileBirthtimes.mockReturnValue(mockFiles);
+
+            const processes = [
+                { pid: 1, command: 'claude', cwd: '/my/project', tty: '' },
+            ];
+
+            const result = locator.discoverLiveSessions(processes);
+            expect(result).toHaveLength(1);
+            expect(result[0].resolvedCwd).toBe('/my/project');
+            // batchGetSessionFileBirthtimes called once with all dirs
+            expect(mockedBatchGetSessionFileBirthtimes).toHaveBeenCalledTimes(1);
+            expect(mockedBatchGetSessionFileBirthtimes).toHaveBeenCalledWith([encodedDir]);
+        });
+
+        it('should return empty when encoded dir does not exist', () => {
+            fs.mkdirSync(projectsDir, { recursive: true });
+
+            // Process CWD /test encodes to -test, but that dir doesn't exist
+            const result = locator.discoverLiveSessions([
+                { pid: 1, command: 'claude', cwd: '/test', tty: '' },
+            ]);
+            expect(result).toEqual([]);
+            expect(mockedBatchGetSessionFileBirthtimes).not.toHaveBeenCalled();
+        });
+
+        it('should deduplicate when multiple processes share same CWD', () => {
+            const encodedDir = path.join(projectsDir, '-my-project');
+            fs.mkdirSync(encodedDir, { recursive: true });
+
+            mockedBatchGetSessionFileBirthtimes.mockReturnValue([
+                { sessionId: 's1', filePath: path.join(encodedDir, 's1.jsonl'), projectDir: encodedDir, birthtimeMs: 1710800324000, resolvedCwd: '' },
+            ]);
+
+            const processes = [
+                { pid: 1, command: 'claude', cwd: '/my/project', tty: '' },
+                { pid: 2, command: 'claude', cwd: '/my/project', tty: '' },
+            ];
+
+            const result = locator.discoverLiveSessions(processes);
+            // Should only call batch once with deduplicated dir
+            expect(mockedBatchGetSessionFileBirthtimes).toHaveBeenCalledTimes(1);
+            expect(mockedBatchGetSessionFileBirthtimes).toHaveBeenCalledWith([encodedDir]);
+            expect(result).toHaveLength(1);
+        });
+
+        it('should skip processes with empty cwd', () => {
+            fs.mkdirSync(projectsDir, { recursive: true });
+
+            const result = locator.discoverLiveSessions([
+                { pid: 1, command: 'claude', cwd: '', tty: '' },
+            ]);
+            expect(result).toEqual([]);
+        });
+    });
+
+    describe('tryPidFileMatching', () => {
+        let tmpDir: string;
+        let sessionsDir: string;
+        let projectsDir: string;
+        let tryMatch: (processes: ProcessInfo[]) => {
+            direct: Array<{ process: ProcessInfo; sessionFile: SessionFile }>;
+            fallback: ProcessInfo[];
+        };
+
+        beforeEach(() => {
+            tmpDir = makeTmpDir();
+            sessionsDir = path.join(tmpDir, 'sessions');
+            projectsDir = path.join(tmpDir, 'projects');
+            fs.mkdirSync(sessionsDir, { recursive: true });
+            tryMatch = bindPidFileMatching(new ClaudeSessionLocator({ projectsDir, sessionsDir }));
+        });
+
+        const makeProc = (pid: number, cwd = '/project/test', startTime?: Date): ProcessInfo => ({
+            pid, command: 'claude', cwd, tty: 'ttys001', startTime,
+        });
+
+        const writePidFile = (pid: number, sessionId: string, cwd: string, startedAt: number) => {
+            fs.writeFileSync(
+                path.join(sessionsDir, `${pid}.json`),
+                JSON.stringify({ pid, sessionId, cwd, startedAt, kind: 'interactive', entrypoint: 'cli' }),
+            );
+        };
+
+        const writeJsonl = (cwd: string, sessionId: string) => {
+            const encoded = cwd.replace(/[^a-zA-Z0-9]/g, '-');
+            const projDir = path.join(projectsDir, encoded);
+            fs.mkdirSync(projDir, { recursive: true });
+            const filePath = path.join(projDir, `${sessionId}.jsonl`);
+            fs.writeFileSync(filePath, JSON.stringify({ type: 'assistant', timestamp: new Date().toISOString() }));
+            return filePath;
+        };
+
+        it('should return direct match when PID file and JSONL both exist within time tolerance', () => {
+            const startTime = new Date();
+            const proc = makeProc(1001, '/project/test', startTime);
+            writePidFile(1001, 'session-abc', '/project/test', startTime.getTime());
+            writeJsonl('/project/test', 'session-abc');
+
+            const { direct, fallback } = tryMatch([proc]);
+
+            expect(direct).toHaveLength(1);
+            expect(fallback).toHaveLength(0);
+            expect(direct[0].sessionFile.sessionId).toBe('session-abc');
+            expect(direct[0].sessionFile.resolvedCwd).toBe('/project/test');
+            expect(direct[0].process.pid).toBe(1001);
+        });
+
+        it('should fall back when PID file exists but JSONL is missing', () => {
+            const startTime = new Date();
+            const proc = makeProc(1002, '/project/test', startTime);
+            writePidFile(1002, 'nonexistent-session', '/project/test', startTime.getTime());
+            // No JSONL file written
+
+            const { direct, fallback } = tryMatch([proc]);
+
+            expect(direct).toHaveLength(0);
+            expect(fallback).toHaveLength(1);
+            expect(fallback[0].pid).toBe(1002);
+        });
+
+        it('should fall back when startedAt is stale (>60s from proc.startTime)', () => {
+            const startTime = new Date();
+            const staleTime = startTime.getTime() - 90_000; // 90 seconds earlier
+            const proc = makeProc(1003, '/project/test', startTime);
+            writePidFile(1003, 'stale-session', '/project/test', staleTime);
+            writeJsonl('/project/test', 'stale-session');
+
+            const { direct, fallback } = tryMatch([proc]);
+
+            expect(direct).toHaveLength(0);
+            expect(fallback).toHaveLength(1);
+        });
+
+        it('should accept PID file when startedAt is within 60s tolerance', () => {
+            const startTime = new Date();
+            const closeTime = startTime.getTime() - 30_000; // 30 seconds earlier — within tolerance
+            const proc = makeProc(1004, '/project/test', startTime);
+            writePidFile(1004, 'close-session', '/project/test', closeTime);
+            writeJsonl('/project/test', 'close-session');
+
+            const { direct, fallback } = tryMatch([proc]);
+
+            expect(direct).toHaveLength(1);
+            expect(fallback).toHaveLength(0);
+        });
+
+        it('should fall back when PID file is absent', () => {
+            const proc = makeProc(1005, '/project/test', new Date());
+            // No PID file written
+
+            const { direct, fallback } = tryMatch([proc]);
+
+            expect(direct).toHaveLength(0);
+            expect(fallback).toHaveLength(1);
+        });
+
+        it('should fall back when PID file contains malformed JSON', () => {
+            const proc = makeProc(1006, '/project/test', new Date());
+            fs.writeFileSync(path.join(sessionsDir, '1006.json'), 'not valid json {{{');
+
+            expect(() => {
+                const { direct, fallback } = tryMatch([proc]);
+                expect(direct).toHaveLength(0);
+                expect(fallback).toHaveLength(1);
+            }).not.toThrow();
+        });
+
+        it('should fall back for all processes when sessions dir does not exist', () => {
+            const missingSessions = bindPidFileMatching(new ClaudeSessionLocator({
+                projectsDir,
+                sessionsDir: path.join(tmpDir, 'nonexistent-sessions'),
+            }));
+            const processes = [makeProc(2001, '/a', new Date()), makeProc(2002, '/b', new Date())];
+
+            const { direct, fallback } = missingSessions(processes);
+
+            expect(direct).toHaveLength(0);
+            expect(fallback).toHaveLength(2);
+        });
+
+        it('should correctly split mixed processes (some with PID files, some without)', () => {
+            const startTime = new Date();
+            const proc1 = makeProc(3001, '/project/one', startTime);
+            const proc2 = makeProc(3002, '/project/two', startTime);
+            const proc3 = makeProc(3003, '/project/three', startTime);
+
+            writePidFile(3001, 'session-one', '/project/one', startTime.getTime());
+            writeJsonl('/project/one', 'session-one');
+            writePidFile(3003, 'session-three', '/project/three', startTime.getTime());
+            writeJsonl('/project/three', 'session-three');
+            // proc2 has no PID file
+
+            const { direct, fallback } = tryMatch([proc1, proc2, proc3]);
+
+            expect(direct).toHaveLength(2);
+            expect(fallback).toHaveLength(1);
+            expect(direct.map((d) => d.process.pid).sort()).toEqual([3001, 3003]);
+            expect(fallback[0].pid).toBe(3002);
+        });
+
+        it('should skip stale-file check when proc.startTime is undefined', () => {
+            const proc = makeProc(4001, '/project/test', undefined); // no startTime
+            writePidFile(4001, 'no-time-session', '/project/test', Date.now() - 999_999);
+            writeJsonl('/project/test', 'no-time-session');
+
+            const { direct, fallback } = tryMatch([proc]);
+
+            // startTime undefined → stale check skipped → direct match
+            expect(direct).toHaveLength(1);
+            expect(fallback).toHaveLength(0);
+        });
+    });
+
+    describe('getProjectDir', () => {
+        let tmpDir: string;
+        let projectsDir: string;
+        let encode: (cwd: string) => string;
+
+        beforeEach(() => {
+            tmpDir = makeTmpDir();
+            projectsDir = path.join(tmpDir, 'projects');
+            encode = bindProjectDir(new ClaudeSessionLocator({
+                projectsDir,
+                sessionsDir: path.join(tmpDir, 'sessions'),
+            }));
+        });
+
+        it('should replace path separators with hyphens', () => {
+            expect(encode('/Users/foo/bar')).toBe(path.join(projectsDir, '-Users-foo-bar'));
+        });
+
+        it('should encode underscores as hyphens (matches Claude Code CLI)', () => {
+            expect(encode('/Users/foo/my_project')).toBe(path.join(projectsDir, '-Users-foo-my-project'));
+        });
+
+        it('should encode dots as hyphens', () => {
+            expect(encode('/Users/foo/.worktrees/x')).toBe(path.join(projectsDir, '-Users-foo--worktrees-x'));
+        });
+
+        it('should collide paths that differ only in non-alphanumeric chars', () => {
+            // The encoding is intentionally lossy — callers must
+            // disambiguate via session JSONL contents, not dir name.
+            expect(encode('/a/b_c')).toBe(encode('/a/b-c'));
+            expect(encode('/a/b_c')).toBe(encode('/a/b.c'));
+        });
+
+        it('should resolve to a real session dir when cwd contains underscores', () => {
+            const cwd = '/Users/foo/my_project';
+            const expectedDir = path.join(projectsDir, '-Users-foo-my-project');
+            fs.mkdirSync(expectedDir, { recursive: true });
+            const sessionFile = path.join(expectedDir, 'session-underscore.jsonl');
+            fs.writeFileSync(sessionFile, '');
+
+            expect(encode(cwd)).toBe(expectedDir);
+            expect(fs.existsSync(path.join(encode(cwd), 'session-underscore.jsonl'))).toBe(true);
+        });
+    });
+});

package/src/__tests__/providers/pi/durable/PiCliProbe.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it, vi } from 'vitest';
+
+describe('PiCliProbe', () => {
+    it('validates documented JSON mode and session capabilities', async () => {
+        const api = await import('../../../../index.js') as Record<string, unknown>;
+        expect(api).toHaveProperty('PiCliProbe');
+        const exec = vi.fn()
+            .mockResolvedValueOnce({ stdout: 'pi 0.52.8', stderr: '' })
+            .mockResolvedValueOnce({ stdout: '--mode json\n--session-id <uuid>\n--session <path|id>', stderr: '' });
+        const Probe = api.PiCliProbe as new (options: unknown) => any;
+        await expect(new Probe({ executable: 'fake-pi', exec }).validate()).resolves.toEqual({
+            executable: 'fake-pi', version: 'pi 0.52.8',
+        });
+        expect(exec.mock.calls).toEqual([['fake-pi', ['--version']], ['fake-pi', ['--help']]]);
+    });
+
+    it('rejects unsupported and unavailable CLIs with sanitized errors', async () => {
+        const api = await import('../../../../index.js') as Record<string, unknown>;
+        const Probe = api.PiCliProbe as new (options: unknown) => any;
+        await expect(new Probe({ exec: vi.fn()
+            .mockResolvedValueOnce({ stdout: '', stderr: '' })
+            .mockResolvedValueOnce({ stdout: '--print only', stderr: '' }) }).validate())
+            .rejects.toMatchObject({ code: 'PI_CLI_UNSUPPORTED' });
+        const unavailable = new Probe({ exec: vi.fn().mockRejectedValue(new Error(`bad\0${'x'.repeat(1000)}`)) });
+        const error = await unavailable.validate().catch((value: Error & { code: string }) => value);
+        expect(error.code).toBe('PI_CLI_UNAVAILABLE');
+        expect(error.message).not.toContain('\0');
+        expect(error.message.length).toBeLessThan(600);
+    });
+
+    it('reports an empty version as unknown', async () => {
+        const api = await import('../../../../index.js') as Record<string, unknown>;
+        const Probe = api.PiCliProbe as new (options: unknown) => any;
+        const exec = vi.fn().mockResolvedValueOnce({ stdout: ' \n', stderr: '' })
+            .mockResolvedValueOnce({ stdout: '--mode json --session-id --session', stderr: '' });
+        await expect(new Probe({ exec }).validate()).resolves.toMatchObject({ version: 'unknown' });
+    });
+});

package/src/__tests__/providers/pi/durable/PiDurableAgentRepository.test.ts

@@ -0,0 +1,32 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { DurableAgentRepository } from '../../../../durable/DurableAgentRepository.js';
+
+const roots: string[] = [];
+
+afterEach(() => {
+    for (const root of roots.splice(0)) fs.rmSync(root, { recursive: true, force: true });
+});
+
+describe('Pi durable-agent repository sessions', () => {
+    it('assigns a non-null session at creation and rejects deferred binding', async () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), 'pi-durable-repository-'));
+        roots.push(root);
+        const cwd = path.join(root, 'project');
+        fs.mkdirSync(cwd);
+        const repository = new DurableAgentRepository({
+            dbPath: path.join(root, 'agents.db'),
+            processInspector: { getIdentity: (pid) => ({ pid, startedAt: 'owner-start' }) },
+        });
+
+        const agent = await repository.create({ name: 'reviewer', cwd, provider: 'pi' });
+        expect(agent).toMatchObject({ provider: 'pi', sessionHealth: 'uninitialized' });
+        expect(agent.providerSessionId).toMatch(/^[0-9a-f-]{36}$/);
+
+        const run = await repository.acquireRun(agent.id);
+        await expect(repository.bindProviderSession(agent.id, run.token, crypto.randomUUID()))
+            .rejects.toThrow('Only Codex durable sessions can be bound after creation.');
+    });
+});