@ai-devkit/agent-manager 0.29.0 → 0.30.0

package/src/__tests__/durable/CodexPrintAgentService.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, it, vi } from 'vitest';
+
+const SESSION = '22222222-2222-4222-8222-222222222222';
+const base = {
+    id: 'id', name: 'reviewer', provider: 'codex', providerSessionId: null, sessionHealth: 'uninitialized',
+};
+
+describe('CodexPrintAgentService', () => {
+    it('constructs default non-billable dependencies without invoking them', async () => {
+        const api = await import('../../index.js') as Record<string, unknown>;
+        const Service = api.CodexPrintAgentService as new () => any;
+        expect(new Service().repository).toBeDefined();
+    });
+
+    it('validates before provider-aware create and never runs Codex', async () => {
+        const api = await import('../../index.js') as Record<string, unknown>;
+        expect(api).toHaveProperty('CodexPrintAgentService');
+        const probe = { validate: vi.fn().mockResolvedValue({ executable: 'codex', version: '0.147.0' }) };
+        const repository = { create: vi.fn().mockResolvedValue(base), list: vi.fn() };
+        const runner = { run: vi.fn() };
+        const Service = api.CodexPrintAgentService as new (options: unknown) => any;
+        await new Service({ repository, probe, runner }).create({ name: 'reviewer', cwd: '/project' });
+        expect(repository.create).toHaveBeenCalledWith({ name: 'reviewer', cwd: '/project', provider: 'codex' });
+        expect(runner.run).not.toHaveBeenCalled();
+    });
+
+    it('binds during first send and explicitly resumes later 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, providerSessionId: SESSION, sessionHealth: 'healthy' }, token: 'two' }),
+            recordProviderProcess: vi.fn(), bindProviderSession: vi.fn(), completeRun: vi.fn(),
+        };
+        const runner = { run: vi.fn().mockImplementation(async (request) => {
+            await request.onSpawn({ pid: 42, startedAt: 'start' });
+            await request.onSession(SESSION);
+            return { sessionId: SESSION, result: 'answer', messages: ['answer'], exitCode: 0 };
+        }) };
+        const Service = api.CodexPrintAgentService as new (options: unknown) => any;
+        const service = new Service({ repository, probe: { validate: vi.fn() }, runner, executable: 'fake-codex' });
+
+        await service.send('reviewer', 'first');
+        await service.send('reviewer', 'later');
+
+        expect(repository.bindProviderSession).toHaveBeenNthCalledWith(1, 'id', 'one', SESSION);
+        expect(repository.bindProviderSession).toHaveBeenNthCalledWith(2, 'id', 'two', SESSION);
+        expect(repository.completeRun).toHaveBeenCalledWith('id', 'one', expect.objectContaining({
+            status: 'succeeded', sessionHealth: 'healthy',
+        }));
+    });
+
+    it('records mismatch separately from unknown failures', async () => {
+        const api = await import('../../index.js') as Record<string, unknown>;
+        const ErrorType = api.CodexPrintError 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(), bindProviderSession: vi.fn(), completeRun,
+        };
+        const Service = api.CodexPrintAgentService as new (options: unknown) => any;
+        const service = new Service({ repository, probe: { validate: vi.fn() }, runner: {
+            run: vi.fn().mockRejectedValue(new ErrorType('mismatch', 'CODEX_SESSION_MISMATCH')),
+        } });
+        await expect(service.send('reviewer', 'x')).rejects.toMatchObject({ code: 'CODEX_SESSION_MISMATCH' });
+        expect(completeRun).toHaveBeenCalledWith('id', 'one', expect.objectContaining({ sessionHealth: 'mismatch' }));
+    });
+
+    it('rejects a non-Codex target without acquiring or mutating it', async () => {
+        const api = await import('../../index.js') as Record<string, unknown>;
+        const Service = api.CodexPrintAgentService as new (options: unknown) => any;
+        const repository = {
+            resolve: vi.fn().mockResolvedValue({ ...base, provider: 'claude' }),
+            acquireRun: vi.fn(), recordProviderProcess: vi.fn(), bindProviderSession: vi.fn(), completeRun: vi.fn(),
+        };
+
+        await expect(new Service({ repository, probe: { validate: vi.fn() }, runner: { run: vi.fn() } })
+            .send('reviewer', 'x')).rejects.toMatchObject({ code: 'CODEX_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.CodexPrintAgentService 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(), bindProviderSession: 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();
+    });
+
+    it('records a repository binding conflict as a session mismatch', async () => {
+        const api = await import('../../index.js') as Record<string, unknown>;
+        const BindingError = api.CodexPrintError 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(),
+            bindProviderSession: vi.fn().mockRejectedValue(new BindingError('binding mismatch', 'CODEX_SESSION_MISMATCH')),
+            completeRun,
+        };
+        const runner = { run: vi.fn().mockImplementation(async (request) => {
+            await request.onSession(SESSION);
+            return { sessionId: SESSION, result: 'x', messages: ['x'], exitCode: 0 };
+        }) };
+        const Service = api.CodexPrintAgentService as new (options: unknown) => any;
+
+        await expect(new Service({ repository, probe: { validate: vi.fn() }, runner }).send('reviewer', 'x'))
+            .rejects.toMatchObject({ code: 'CODEX_SESSION_MISMATCH' });
+        expect(completeRun).toHaveBeenCalledWith('id', 'one', expect.objectContaining({ sessionHealth: 'mismatch' }));
+    });
+
+    it('rejects missing and ambiguous records before acquiring a run', async () => {
+        const api = await import('../../index.js') as Record<string, unknown>;
+        const Service = api.CodexPrintAgentService as new (options: unknown) => any;
+        const repository = {
+            list: vi.fn(), create: vi.fn(), resolve: vi.fn().mockResolvedValueOnce(null).mockResolvedValueOnce([base, base]),
+            acquireRun: vi.fn(), recordProviderProcess: vi.fn(), bindProviderSession: vi.fn(), completeRun: vi.fn(),
+        };
+        const service = new Service({ repository, probe: { validate: vi.fn() }, runner: { run: vi.fn() } });
+        await expect(service.send('missing', 'x')).rejects.toMatchObject({ code: 'DURABLE_AGENT_NOT_FOUND' });
+        await expect(service.send('ambiguous', 'x')).rejects.toMatchObject({ code: 'CODEX_UNSUPPORTED' });
+        expect(repository.acquireRun).not.toHaveBeenCalled();
+    });
+});

package/src/__tests__/durable/CodexPrintRunner.test.ts

@@ -0,0 +1,189 @@
+import { EventEmitter } from 'node:events';
+import { PassThrough, Writable } from 'node:stream';
+import { describe, expect, it, vi } from 'vitest';
+import type { CodexDurableAgent } from '../../index.js';
+
+const SESSION = '22222222-2222-4222-8222-222222222222';
+
+function agent(providerSessionId: string | null = null): CodexDurableAgent {
+    return {
+        id: '11111111-1111-4111-8111-111111111111', name: 'reviewer', provider: 'codex', mode: 'durable',
+        cwd: '/project', providerSessionId, state: 'running', sessionHealth: 'uninitialized',
+        createdAt: '', updatedAt: '', lastActiveAt: null, lastResult: null, activeRun: null,
+    };
+}
+
+function fakeSpawn(lines: string[], exitCode = 0, chunks = false) {
+    const promptChunks: Buffer[] = [];
+    const child = new EventEmitter() as any;
+    child.pid = 4242;
+    child.stdout = new PassThrough();
+    child.stderr = new PassThrough();
+    child.kill = vi.fn();
+    child.stdin = new Writable({
+        write(chunk, _encoding, callback) { promptChunks.push(Buffer.from(chunk)); callback(); },
+        final(callback) {
+            const output = lines.join('\n');
+            if (chunks) {
+                const bytes = Buffer.from(output);
+                child.stdout.write(bytes.subarray(0, 7));
+                child.stdout.write(bytes.subarray(7));
+            } else child.stdout.write(output);
+            child.stdout.end();
+            queueMicrotask(() => child.emit('close', exitCode, null));
+            callback();
+        },
+    });
+    const spawn = vi.fn(() => child);
+    return { child, spawn, promptChunks };
+}
+
+function events(session = SESSION): string[] {
+    return [
+        JSON.stringify({ type: 'thread.started', thread_id: session }),
+        JSON.stringify({ type: 'turn.started' }),
+        JSON.stringify({ type: 'future.event', anything: true }),
+        JSON.stringify({ type: 'item.completed', item: { type: 'agent_message', text: 'first' } }),
+        JSON.stringify({ type: 'item.completed', item: { type: 'agent_message', text: 'final' } }),
+        JSON.stringify({ type: 'turn.completed' }),
+        '',
+    ];
+}
+
+async function runner(fixture: ReturnType<typeof fakeSpawn>, maxLineBytes?: number) {
+    const api = await import('../../index.js') as Record<string, unknown>;
+    expect(api).toHaveProperty('CodexPrintRunner');
+    const Runner = api.CodexPrintRunner as new (options: unknown) => any;
+    return new Runner({ spawn: fixture.spawn, maxLineBytes, processInspector: {
+        getIdentity: () => ({ pid: 4242, startedAt: 'provider-start' }),
+    } });
+}
+
+describe('CodexPrintRunner', () => {
+    it('constructs default process dependencies without spawning', async () => {
+        const api = await import('../../index.js') as Record<string, unknown>;
+        const Runner = api.CodexPrintRunner as new () => any;
+        expect(new Runner()).toBeDefined();
+    });
+
+    it('binds an initial thread before returning ordered assistant output', async () => {
+        const fixture = fakeSpawn(events(), 0, true);
+        const instance = await runner(fixture);
+        const order: string[] = [];
+        const result = await instance.run({
+            agent: agent(), prompt: 'secret prompt', executable: 'fake-codex',
+            onSpawn: async () => { expect(fixture.promptChunks).toHaveLength(0); order.push('spawn'); },
+            onSession: async (id: string) => { expect(id).toBe(SESSION); order.push('session'); },
+        });
+
+        expect(order).toEqual(['spawn', 'session']);
+        expect(fixture.spawn).toHaveBeenCalledWith('fake-codex', ['exec', '--json', '-'], expect.objectContaining({
+            cwd: '/project', shell: false, stdio: ['pipe', 'pipe', 'pipe'],
+        }));
+        expect(JSON.stringify(fixture.spawn.mock.calls)).not.toContain('secret prompt');
+        expect(Buffer.concat(fixture.promptChunks).toString()).toBe('secret prompt');
+        expect(result).toEqual({ sessionId: SESSION, result: 'final', messages: ['first', 'final'], exitCode: 0 });
+    });
+
+    it('resumes the exact stored UUID and rejects a mismatch', async () => {
+        const mismatch = '33333333-3333-4333-8333-333333333333';
+        const fixture = fakeSpawn(events(mismatch));
+        const instance = await runner(fixture);
+        await expect(instance.run({ agent: agent(SESSION), prompt: 'later', onSpawn: vi.fn(), onSession: vi.fn() }))
+            .rejects.toMatchObject({ code: 'CODEX_SESSION_MISMATCH' });
+        expect(fixture.spawn.mock.calls[0]![1]).toEqual(['exec', 'resume', '--json', SESSION, '-']);
+    });
+
+    it.each([
+        ['malformed JSON', ['{bad\n'], 'CODEX_PROTOCOL'],
+        ['non-object JSON', ['[]\n'], 'CODEX_PROTOCOL'],
+        ['truncated JSON', ['{}'], 'CODEX_PROTOCOL'],
+        ['missing thread', [JSON.stringify({ type: 'item.completed', item: { type: 'agent_message', text: 'x' } }), JSON.stringify({ type: 'turn.completed' }), ''], 'CODEX_PROTOCOL'],
+        ['missing assistant', [JSON.stringify({ type: 'thread.started', thread_id: SESSION }), JSON.stringify({ type: 'turn.completed' }), ''], 'CODEX_RESULT_MISSING'],
+        ['missing completion', [JSON.stringify({ type: 'thread.started', thread_id: SESSION }), JSON.stringify({ type: 'item.completed', item: { type: 'agent_message', text: 'x' } }), ''], 'CODEX_PROTOCOL'],
+    ])('rejects %s', async (_name, lines, code) => {
+        const fixture = fakeSpawn(lines as string[]);
+        await expect((await runner(fixture)).run({
+            agent: agent(), prompt: 'x', onSpawn: vi.fn(), onSession: vi.fn(),
+        })).rejects.toMatchObject({ code });
+    });
+
+    it('rejects oversized output, non-zero exit, and missing process identity without leaking stderr', async () => {
+        const oversized = fakeSpawn([`${'x'.repeat(20)}\n`]);
+        await expect((await runner(oversized, 10)).run({
+            agent: agent(), prompt: 'x', onSpawn: vi.fn(), onSession: vi.fn(),
+        })).rejects.toMatchObject({ code: 'CODEX_PROTOCOL' });
+        const oversizedWithoutNewline = fakeSpawn(['x'.repeat(20)]);
+        await expect((await runner(oversizedWithoutNewline, 10)).run({
+            agent: agent(), prompt: 'x', onSpawn: vi.fn(), onSession: vi.fn(),
+        })).rejects.toMatchObject({ code: 'CODEX_PROTOCOL' });
+
+        const failed = fakeSpawn(events(), 1);
+        failed.child.stderr.end('secret-looking provider diagnostic');
+        await expect((await runner(failed)).run({
+            agent: agent(), prompt: 'x', onSpawn: vi.fn(), onSession: vi.fn(),
+        })).rejects.toMatchObject({ code: 'CODEX_PROCESS' });
+
+        const missing = fakeSpawn([]);
+        missing.child.pid = undefined;
+        await expect((await runner(missing)).run({
+            agent: agent(), prompt: 'x', onSpawn: vi.fn(), onSession: vi.fn(),
+        })).rejects.toMatchObject({ code: 'CODEX_PROCESS' });
+    });
+
+    it('rejects invalid or duplicate thread identities', async () => {
+        for (const lines of [
+            [JSON.stringify({ type: 'thread.started', thread_id: 'bad' }), ''],
+            [
+                JSON.stringify({ type: 'thread.started', thread_id: SESSION }),
+                JSON.stringify({ type: 'thread.started', thread_id: SESSION }),
+                '',
+            ],
+        ]) {
+            const fixture = fakeSpawn(lines);
+            await expect((await runner(fixture)).run({
+                agent: agent(), prompt: 'x', onSpawn: vi.fn(), onSession: vi.fn(),
+            })).rejects.toMatchObject({ code: 'CODEX_PROTOCOL' });
+        }
+    });
+
+    it('classifies callback processing failure and kills when spawn persistence fails', async () => {
+        const callbackFailure = fakeSpawn(events());
+        await expect((await runner(callbackFailure)).run({
+            agent: agent(), prompt: 'x', onSpawn: vi.fn(),
+            onSession: vi.fn().mockRejectedValue(new Error('storage unavailable')),
+        })).rejects.toMatchObject({ code: 'CODEX_PROTOCOL' });
+
+        const spawnFailure = fakeSpawn([]);
+        const failure = new Error('cannot persist process');
+        await expect((await runner(spawnFailure)).run({
+            agent: agent(), prompt: 'x', onSpawn: vi.fn().mockRejectedValue(failure), onSession: vi.fn(),
+        })).rejects.toBe(failure);
+        expect(spawnFailure.child.kill).toHaveBeenCalledOnce();
+    });
+
+    it('rejects an unverifiable positive PID', async () => {
+        const api = await import('../../index.js') as Record<string, unknown>;
+        const fixture = fakeSpawn([]);
+        const Runner = api.CodexPrintRunner as new (options: unknown) => any;
+        const instance = new Runner({ spawn: fixture.spawn, processInspector: { getIdentity: () => null } });
+        await expect(instance.run({
+            agent: agent(), prompt: 'x', onSpawn: vi.fn(), onSession: vi.fn(),
+        })).rejects.toMatchObject({ code: 'CODEX_PROCESS' });
+        expect(fixture.child.kill).toHaveBeenCalledOnce();
+    });
+
+    it('classifies a child spawn error as a process failure', async () => {
+        const fixture = fakeSpawn([]);
+        fixture.child.stdin = new Writable({
+            write(_chunk, _encoding, callback) { callback(); },
+            final(callback) {
+                queueMicrotask(() => fixture.child.emit('error', new Error('spawn failed')));
+                callback();
+            },
+        });
+        await expect((await runner(fixture)).run({
+            agent: agent(), prompt: 'x', onSpawn: vi.fn(), onSession: vi.fn(),
+        })).rejects.toMatchObject({ code: 'CODEX_PROCESS' });
+    });
+});

package/src/__tests__/fixtures/fake-codex.cjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+const fs = require('node:fs');
+
+const SESSION = '22222222-2222-4222-8222-222222222222';
+const MISMATCH = '33333333-3333-4333-8333-333333333333';
+const args = process.argv.slice(2);
+
+if (args[0] === '--version') {
+  process.stdout.write('codex-cli 0.147.0\n');
+  process.exit(0);
+}
+if (args[0] === 'exec' && args.at(-1) === '--help') {
+  process.stdout.write(args[1] === 'resume'
+    ? 'Usage: codex exec resume [SESSION_ID] [PROMPT]\n--json\n- stdin\n'
+    : 'Usage: codex exec [PROMPT]\nresume\n--json\n- stdin\n');
+  process.exit(0);
+}
+
+let prompt = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { prompt += chunk; });
+process.stdin.on('end', () => {
+  const mode = process.env.AI_DEVKIT_FAKE_CODEX_MODE || 'success';
+  const isResume = args[1] === 'resume';
+  const requested = isResume ? args[3] : null;
+  const sessionId = mode === 'mismatch' ? MISMATCH : (requested || SESSION);
+  const capture = process.env.AI_DEVKIT_FAKE_CODEX_CAPTURE;
+  if (capture) fs.appendFileSync(capture, `${JSON.stringify({ args, prompt, cwd: process.cwd() })}\n`);
+  if (mode === 'fail-before-bind') process.exit(1);
+  if (mode !== 'missing-thread') process.stdout.write(`${JSON.stringify({ type: 'thread.started', thread_id: sessionId })}\n`);
+  if (mode === 'fail-after-bind') process.exit(1);
+  if (mode === 'malformed') return process.stdout.write('{bad\n');
+  if (mode === 'oversized') return process.stdout.write(`${'x'.repeat(1024 * 1024 + 1)}\n`);
+  if (mode === 'truncated') return process.stdout.write('{');
+  process.stdout.write(`${JSON.stringify({ type: 'turn.started' })}\n`);
+  if (mode !== 'missing-result') {
+    process.stdout.write(`${JSON.stringify({ type: 'item.completed', item: { id: 'item_0', type: 'agent_message', text: 'first' } })}\n`);
+    process.stdout.write(`${JSON.stringify({ type: 'item.completed', item: { id: 'item_1', type: 'agent_message', text: `answer:${prompt}` } })}\n`);
+  }
+  if (mode !== 'missing-completion') process.stdout.write(`${JSON.stringify({ type: 'turn.completed', usage: {} })}\n`);
+  if (mode === 'stderr-failure') {
+    process.stderr.write('secret-looking diagnostic');
+    process.exitCode = 1;
+  }
+});

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

@@ -1,17 +1,15 @@
 import { describe, expect, it, vi } from 'vitest';
+import { ClaudeCliProbe } from '../../providers/claude/durable/ClaudeCliProbe.js';
 
 describe('ClaudeCliProbe', () => {
     it('validates only version/help and requires the print session flags', async () => {
-        const api = await import('../../index.js') as Record<string, unknown>;
-        expect(api).toHaveProperty('ClaudeCliProbe');
         const exec = vi.fn()
             .mockResolvedValueOnce({ stdout: '2.1.220\n', stderr: '' })
             .mockResolvedValueOnce({
                 stdout: '--print --session-id --resume --output-format stream-json', stderr: '',
             });
-        const Probe = api.ClaudeCliProbe as new (options: unknown) => { validate(): Promise<unknown> };
 
-        await expect(new Probe({ exec }).validate()).resolves.toEqual({
+        await expect(new ClaudeCliProbe({ exec }).validate()).resolves.toEqual({
             executable: 'claude', version: '2.1.220',
         });
         expect(exec.mock.calls).toEqual([
@@ -21,12 +19,10 @@ describe('ClaudeCliProbe', () => {
     });
 
     it('rejects a CLI missing a required capability', async () => {
-        const api = await import('../../index.js') as Record<string, unknown>;
         const exec = vi.fn()
             .mockResolvedValueOnce({ stdout: 'old', stderr: '' })
             .mockResolvedValueOnce({ stdout: '--print only', stderr: '' });
-        const Probe = api.ClaudeCliProbe as new (options: unknown) => { validate(): Promise<unknown> };
 
-        await expect(new Probe({ exec }).validate()).rejects.toMatchObject({ code: 'CLAUDE_CLI_UNSUPPORTED' });
+        await expect(new ClaudeCliProbe({ exec }).validate()).rejects.toMatchObject({ code: 'CLAUDE_CLI_UNSUPPORTED' });
     });
 });

package/src/__tests__/print/ClaudePrintAgent.integration.test.ts

@@ -1,22 +1,16 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { afterEach, describe, expect, it } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 import {
-    ClaudeCliProbe,
     ClaudePrintAgentService,
-    ClaudePrintRunner,
     DurableAgentRepository,
     type ProcessInspector,
 } from '../../index.js';
 
 const roots: string[] = [];
-const originalCapture = process.env.AI_DEVKIT_FAKE_CLAUDE_CAPTURE;
 
 afterEach(() => {
-    if (originalCapture === undefined) delete process.env.AI_DEVKIT_FAKE_CLAUDE_CAPTURE;
-    else process.env.AI_DEVKIT_FAKE_CLAUDE_CAPTURE = originalCapture;
     for (const root of roots.splice(0)) fs.rmSync(root, { recursive: true, force: true });
 });
 
@@ -26,9 +20,6 @@ describe('Claude durable-agent fake-provider journey', () => {
         roots.push(root);
         const cwd = path.join(root, 'project');
         fs.mkdirSync(cwd);
-        const capture = path.join(root, 'capture.jsonl');
-        process.env.AI_DEVKIT_FAKE_CLAUDE_CAPTURE = capture;
-        const executable = fileURLToPath(new URL('../fixtures/fake-claude.cjs', import.meta.url));
         const processInspector: ProcessInspector = {
             getIdentity: (pid) => ({ pid, startedAt: `process-${pid}` }),
         };
@@ -36,26 +27,25 @@ describe('Claude durable-agent fake-provider journey', () => {
             dbPath: path.join(root, 'state', 'agents.db'),
             processInspector,
         });
+        const runner = {
+            run: vi.fn().mockImplementation(async (request) => {
+                await request.onSpawn({ pid: 42, startedAt: 'process-42' });
+                return { sessionId: request.agent.providerSessionId, result: `answer:${request.prompt}`, exitCode: 0 };
+            }),
+        };
         const service = new ClaudePrintAgentService({
             repository,
-            probe: new ClaudeCliProbe({ executable }),
-            runner: new ClaudePrintRunner({ processInspector }),
-            executable,
+            probe: { validate: vi.fn() },
+            runner,
         });
 
         const created = await service.create({ name: 'reviewer', cwd });
-        expect(fs.existsSync(capture)).toBe(false);
 
         await expect(service.send(created.id, 'first secret')).resolves.toMatchObject({ result: 'answer:first secret' });
         await expect(service.send(created.id, 'follow up')).resolves.toMatchObject({ result: 'answer:follow up' });
 
-        const invocations = fs.readFileSync(capture, 'utf8').trim().split('\n').map((line) => JSON.parse(line));
-        expect(invocations[0]).toMatchObject({ prompt: 'first secret', cwd: fs.realpathSync(cwd) });
-        expect(invocations[0].args).toContain('--session-id');
-        expect(invocations[0].args).not.toContain('first secret');
-        expect(invocations[1]).toMatchObject({ prompt: 'follow up', cwd: fs.realpathSync(cwd) });
-        expect(invocations[1].args).toContain('--resume');
-        expect(invocations[1].args[invocations[1].args.indexOf('--resume') + 1]).toBe(created.providerSessionId);
+        expect(runner.run.mock.calls[0][0]).toMatchObject({ firstRun: true, prompt: 'first secret' });
+        expect(runner.run.mock.calls[1][0]).toMatchObject({ firstRun: false, prompt: 'follow up' });
 
         const persisted = await repository.getById(created.id);
         expect(persisted).toMatchObject({ state: 'ready', sessionHealth: 'healthy' });

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