@ai-devkit/agent-manager 0.29.0 → 0.30.0

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.');
+    });
+});

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

@@ -0,0 +1,69 @@
+import { describe, expect, it, vi } from 'vitest';
+const SESSION = '22222222-2222-4222-8222-222222222222';
+const base = { id: 'id', name: 'reviewer', provider: 'pi', providerSessionId: SESSION, sessionHealth: 'uninitialized' };
+
+describe('PiPrintAgentService', () => {
+    it('probes before provider-aware create', async () => {
+        const api = await import('../../../../index.js') as Record<string, unknown>; expect(api).toHaveProperty('PiPrintAgentService');
+        const probe = { validate: vi.fn() }; const repository = { create: vi.fn().mockResolvedValue(base), list: vi.fn() }; const runner = { run: vi.fn() };
+        const Service = api.PiPrintAgentService as new (options: unknown) => any;
+        await new Service({ repository, probe, runner }).create({ name: 'reviewer', cwd: '/project' });
+        expect(probe.validate).toHaveBeenCalledOnce(); expect(repository.create).toHaveBeenCalledWith({ name: 'reviewer', cwd: '/project', provider: 'pi' });
+    });
+
+    it('records successful first and resumed sends', async () => {
+        const api = await import('../../../../index.js') as Record<string, unknown>;
+        const repository = { list: vi.fn(), resolve: vi.fn().mockResolvedValue(base), acquireRun: vi.fn()
+            .mockResolvedValueOnce({ agent: base, token: 'one' }).mockResolvedValueOnce({ agent: { ...base, sessionHealth: 'healthy' }, token: 'two' }),
+            recordProviderProcess: vi.fn(), completeRun: vi.fn() };
+        const runner = { run: vi.fn(async (request) => { await request.onSpawn({ pid: 42, startedAt: 'start' }); return { sessionId: SESSION, result: 'answer', messages: ['answer'], exitCode: 0 }; }) };
+        const Service = api.PiPrintAgentService as new (options: unknown) => any; const service = new Service({ repository, probe: { validate: vi.fn() }, runner });
+        await service.send('reviewer', 'first'); await service.send('reviewer', 'later');
+        expect(repository.completeRun).toHaveBeenCalledWith('id', 'one', expect.objectContaining({ status: 'succeeded', sessionHealth: 'healthy' }));
+    });
+
+    it('records mismatches and rejects missing and ambiguous records', async () => {
+        const api = await import('../../../../index.js') as Record<string, unknown>; const ErrorType = api.PiPrintError as new (message: string, code: string) => Error;
+        const completeRun = vi.fn(); const repository = { list: vi.fn(), resolve: vi.fn().mockResolvedValue(base), acquireRun: vi.fn().mockResolvedValue({ agent: base, token: 'one' }), recordProviderProcess: vi.fn(), completeRun };
+        const Service = api.PiPrintAgentService as new (options: unknown) => any;
+        await expect(new Service({ repository, probe: { validate: vi.fn() }, runner: { run: vi.fn().mockRejectedValue(new ErrorType('bad', 'PI_SESSION_MISMATCH')) } }).send('reviewer', 'x'))
+            .rejects.toMatchObject({ code: 'PI_SESSION_MISMATCH' });
+        expect(completeRun).toHaveBeenCalledWith('id', 'one', expect.objectContaining({ sessionHealth: 'mismatch' }));
+        const earlyRepository = { ...repository, resolve: vi.fn().mockResolvedValueOnce(null).mockResolvedValueOnce([base, base]), acquireRun: vi.fn() };
+        const early = new Service({ repository: earlyRepository, probe: { validate: vi.fn() }, runner: { run: vi.fn() } });
+        await expect(early.send('missing', 'x')).rejects.toMatchObject({ code: 'DURABLE_AGENT_NOT_FOUND' });
+        await expect(early.send('many', 'x')).rejects.toMatchObject({ code: 'PI_UNSUPPORTED' });
+    });
+
+    it('rejects a non-Pi target without acquiring or mutating it', async () => {
+        const api = await import('../../../../index.js') as Record<string, unknown>;
+        const Service = api.PiPrintAgentService as new (options: unknown) => any;
+        const repository = {
+            resolve: vi.fn().mockResolvedValue({ ...base, provider: 'claude' }),
+            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: 'PI_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.PiPrintAgentService as new (options: unknown) => any;
+        const completionFailure = new Error('completion failed');
+        const repository = {
+            resolve: vi.fn().mockResolvedValue(base),
+            acquireRun: vi.fn().mockResolvedValue({ agent: base, token: 'one' }),
+            recordProviderProcess: vi.fn(), completeRun: vi.fn().mockRejectedValue(completionFailure),
+        };
+        const runner = { run: vi.fn().mockResolvedValue({
+            sessionId: SESSION, result: 'answer', messages: ['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__/providers/pi/durable/PiPrintProtocol.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+import { buildPiPrintArgs, readPiAssistantText, readPiSessionId } from '../../../../providers/pi/durable/PiPrintProtocol.js';
+
+const SESSION = '22222222-2222-4222-8222-222222222222';
+
+describe('Pi print pure protocol mapping', () => {
+    it('maps first and resumed runs to exact documented arguments', () => {
+        expect(buildPiPrintArgs(SESSION, true)).toEqual(['--mode', 'json', '--session-id', SESSION]);
+        expect(buildPiPrintArgs(SESSION, false)).toEqual(['--mode', 'json', '--session', SESSION]);
+    });
+
+    it('accepts one expected UUID and rejects invalid, duplicate, and mismatched identities', () => {
+        expect(readPiSessionId({ id: SESSION }, null, SESSION)).toBe(SESSION);
+        expect(() => readPiSessionId({}, null, SESSION)).toThrowError(expect.objectContaining({ code: 'PI_PROTOCOL' }));
+        expect(() => readPiSessionId({ id: [SESSION] }, null, SESSION))
+            .toThrowError(expect.objectContaining({ code: 'PI_PROTOCOL' }));
+        expect(() => readPiSessionId({ id: SESSION }, SESSION, SESSION)).toThrowError(expect.objectContaining({ code: 'PI_PROTOCOL' }));
+        expect(() => readPiSessionId({ id: '33333333-3333-4333-8333-333333333333' }, null, SESSION))
+            .toThrowError(expect.objectContaining({ code: 'PI_SESSION_MISMATCH' }));
+    });
+
+    it('extracts only non-empty completed assistant text', () => {
+        expect(readPiAssistantText({ type: 'future' })).toBeNull();
+        expect(readPiAssistantText({ type: 'message_end' })).toBeNull();
+        expect(readPiAssistantText({ type: 'message_end', message: [] })).toBeNull();
+        expect(readPiAssistantText({ type: 'message_end', message: { role: 'user', content: 'no' } })).toBeNull();
+        expect(readPiAssistantText({ type: 'message_end', message: { role: 'assistant', content: ' ' } })).toBeNull();
+        expect(readPiAssistantText({ type: 'message_end', message: { role: 'assistant', content: 'answer' } })).toBe('answer');
+        expect(readPiAssistantText({ type: 'message_end', message: { role: 'assistant', content: null } })).toBeNull();
+        expect(readPiAssistantText({ type: 'message_end', message: { role: 'assistant', content: [null, [], { type: 'thinking' }] } })).toBeNull();
+        expect(readPiAssistantText({ type: 'message_end', message: { role: 'assistant', content: [{ type: 'text', text: 'a' }, { type: 'text', text: 1 }, { type: 'text', text: 'b' }] } })).toBe('ab');
+    });
+});