@ai-devkit/agent-manager 0.25.0 → 0.26.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-devkit/agent-manager",
-  "version": "0.25.0",
+  "version": "0.26.1",
   "type": "module",
   "description": "Standalone agent detection and management utilities for AI DevKit",
   "main": "dist/index.js",

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

@@ -1133,6 +1133,52 @@ describe('CodexAdapter', () => {
                 expect(session.summary).toBe('Last message');
             });
 
+            it('should extract summary from current Codex response_item messages', () => {
+                const parseSession = (adapter as any).parseSession.bind(adapter);
+                const filePath = path.join(tmpDir, 'response-item-summary.jsonl');
+                fs.writeFileSync(filePath, [
+                    JSON.stringify({ type: 'session_meta', payload: { id: 'sess-ri', timestamp: '2026-03-18T15:00:00Z', cwd: '/repo' } }),
+                    JSON.stringify({
+                        type: 'response_item',
+                        timestamp: '2026-03-18T15:01:00Z',
+                        payload: {
+                            type: 'message',
+                            role: 'assistant',
+                            content: [{ type: 'output_text', text: 'Parsed from current schema' }],
+                        },
+                    }),
+                ].join('\n'));
+
+                const session = parseSession(undefined, filePath);
+                expect(session.summary).toBe('Parsed from current schema');
+                expect(session.lastPayloadType).toBe('agent_message');
+            });
+
+            it('should treat completed Codex AgentMessage events as waiting for list status', () => {
+                const parseSession = (adapter as any).parseSession.bind(adapter);
+                const determineStatus = (adapter as any).determineStatus.bind(adapter);
+                const filePath = path.join(tmpDir, 'agent-message-status.jsonl');
+                fs.writeFileSync(filePath, [
+                    JSON.stringify({ type: 'session_meta', payload: { id: 'sess-am', timestamp: '2026-03-18T15:00:00Z', cwd: '/repo' } }),
+                    JSON.stringify({
+                        type: 'event_msg',
+                        timestamp: new Date().toISOString(),
+                        payload: {
+                            type: 'item_completed',
+                            item: {
+                                type: 'AgentMessage',
+                                content: [{ type: 'Text', text: 'Waiting for the user now' }],
+                            },
+                        },
+                    }),
+                ].join('\n'));
+
+                const session = parseSession(undefined, filePath);
+                expect(session.summary).toBe('Waiting for the user now');
+                expect(session.lastPayloadType).toBe('agent_message');
+                expect(determineStatus(session)).toBe(AgentStatus.WAITING);
+            });
+
             it('should handle malformed JSON lines gracefully', () => {
                 const parseSession = (adapter as any).parseSession.bind(adapter);
                 const filePath = path.join(tmpDir, 'malformed.jsonl');
@@ -1212,6 +1258,115 @@ describe('CodexAdapter', () => {
             expect(messages[1]).toEqual({ role: 'assistant', content: 'I found the issue', timestamp: '2026-03-27T10:00:05Z' });
         });
 
+        it('should parse Codex response_item message records', () => {
+            const filePath = writeJsonl([
+                { type: 'session_meta', payload: { id: 'sess-1', cwd: '/repo', timestamp: '2026-03-27T10:00:00Z' } },
+                {
+                    type: 'response_item',
+                    timestamp: '2026-03-27T10:00:01Z',
+                    payload: {
+                        type: 'message',
+                        role: 'user',
+                        content: [{ type: 'input_text', text: 'Fix the bug' }],
+                    },
+                },
+                {
+                    type: 'response_item',
+                    timestamp: '2026-03-27T10:00:05Z',
+                    payload: {
+                        type: 'message',
+                        role: 'assistant',
+                        content: [{ type: 'output_text', text: 'I found the issue' }],
+                    },
+                },
+            ]);
+
+            const messages = adapter.getConversation(filePath);
+            expect(messages).toHaveLength(2);
+            expect(messages[0]).toEqual({ role: 'user', content: 'Fix the bug', timestamp: '2026-03-27T10:00:01Z' });
+            expect(messages[1]).toEqual({ role: 'assistant', content: 'I found the issue', timestamp: '2026-03-27T10:00:05Z' });
+        });
+
+        it('should parse completed Codex AgentMessage event records', () => {
+            const filePath = writeJsonl([
+                { type: 'session_meta', payload: { id: 'sess-1', cwd: '/repo', timestamp: '2026-03-27T10:00:00Z' } },
+                {
+                    type: 'event_msg',
+                    timestamp: '2026-03-27T10:00:05Z',
+                    payload: {
+                        type: 'item_completed',
+                        item: {
+                            type: 'AgentMessage',
+                            content: [{ type: 'Text', text: 'I found the issue' }],
+                        },
+                    },
+                },
+            ]);
+
+            const messages = adapter.getConversation(filePath);
+            expect(messages).toEqual([
+                { role: 'assistant', content: 'I found the issue', timestamp: '2026-03-27T10:00:05Z' },
+            ]);
+        });
+
+        it('should not duplicate mirrored current Codex message records', () => {
+            const filePath = writeJsonl([
+                { type: 'session_meta', payload: { id: 'sess-1', cwd: '/repo', timestamp: '2026-03-27T10:00:00Z' } },
+                {
+                    type: 'response_item',
+                    timestamp: '2026-03-27T10:00:01Z',
+                    payload: {
+                        type: 'message',
+                        role: 'user',
+                        content: [{ type: 'input_text', text: 'Fix the bug' }],
+                        internal_chat_message_metadata_passthrough: { turn_id: 'turn-1' },
+                    },
+                },
+                {
+                    type: 'event_msg',
+                    timestamp: '2026-03-27T10:00:01.001Z',
+                    payload: {
+                        type: 'item_completed',
+                        turn_id: 'turn-1',
+                        item: {
+                            type: 'UserMessage',
+                            content: [{ type: 'text', text: 'Fix the bug' }],
+                        },
+                    },
+                },
+                {
+                    type: 'event_msg',
+                    timestamp: '2026-03-27T10:00:05Z',
+                    payload: {
+                        type: 'item_completed',
+                        turn_id: 'turn-1',
+                        item: {
+                            type: 'AgentMessage',
+                            id: 'msg-1',
+                            content: [{ type: 'Text', text: 'I found the issue' }],
+                        },
+                    },
+                },
+                {
+                    type: 'response_item',
+                    timestamp: '2026-03-27T10:00:05.005Z',
+                    payload: {
+                        type: 'message',
+                        id: 'msg-1',
+                        role: 'assistant',
+                        content: [{ type: 'output_text', text: 'I found the issue' }],
+                        internal_chat_message_metadata_passthrough: { turn_id: 'turn-1' },
+                    },
+                },
+            ]);
+
+            const messages = adapter.getConversation(filePath);
+            expect(messages).toEqual([
+                { role: 'user', content: 'Fix the bug', timestamp: '2026-03-27T10:00:01Z' },
+                { role: 'assistant', content: 'I found the issue', timestamp: '2026-03-27T10:00:05.005Z' },
+            ]);
+        });
+
         it('should skip session_meta entry', () => {
             const filePath = writeJsonl([
                 { type: 'session_meta', payload: { id: 'sess-1', cwd: '/repo', timestamp: '2026-03-27T10:00:00Z' } },

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

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+const fs = require('node:fs');
+
+const args = process.argv.slice(2);
+if (args[0] === '--version') {
+  process.stdout.write('fake-claude 2.1.220\n');
+  process.exit(0);
+}
+if (args[0] === '--help') {
+  process.stdout.write('--print -p --session-id --resume --output-format stream-json --verbose\n');
+  process.exit(0);
+}
+
+let prompt = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { prompt += chunk; });
+process.stdin.on('end', () => {
+  const flag = args.includes('--session-id') ? '--session-id' : '--resume';
+  const sessionId = args[args.indexOf(flag) + 1];
+  const capture = process.env.AI_DEVKIT_FAKE_CLAUDE_CAPTURE;
+  if (capture) fs.appendFileSync(capture, `${JSON.stringify({ args, prompt, cwd: process.cwd() })}\n`);
+  process.stdout.write(`${JSON.stringify({ type: 'system', subtype: 'init', session_id: sessionId })}\n`);
+  process.stdout.write(`${JSON.stringify({ type: 'result', session_id: sessionId, result: `answer:${prompt}` })}\n`);
+});

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

@@ -0,0 +1,32 @@
+import { describe, expect, it, vi } from 'vitest';
+
+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({
+            executable: 'claude', version: '2.1.220',
+        });
+        expect(exec.mock.calls).toEqual([
+            ['claude', ['--version']],
+            ['claude', ['--help']],
+        ]);
+    });
+
+    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' });
+    });
+});

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

@@ -0,0 +1,56 @@
+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 {
+    ClaudeCliProbe,
+    ClaudePrintAgentService,
+    ClaudePrintRunner,
+    PrintAgentStore,
+} 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 });
+});
+
+describe('Claude print-agent fake-provider journey', () => {
+    it('creates without invocation, then starts and resumes the same session through stdin', async () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), 'print-agent-integration-'));
+        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 store = new PrintAgentStore({ filePath: path.join(root, 'state', 'print-agents.json') });
+        const service = new ClaudePrintAgentService({
+            store,
+            probe: new ClaudeCliProbe({ executable }),
+            runner: new ClaudePrintRunner(),
+            executable,
+        });
+
+        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);
+
+        const persisted = await store.getById(created.id);
+        expect(persisted).toMatchObject({ state: 'ready', sessionHealth: 'healthy' });
+    });
+});

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

@@ -0,0 +1,46 @@
+import { describe, expect, it, vi } from 'vitest';
+
+describe('ClaudePrintAgentService', () => {
+    it('validates before create and does not run Claude', async () => {
+        const api = await import('../../index.js') as Record<string, unknown>;
+        expect(api).toHaveProperty('ClaudePrintAgentService');
+        const probe = { validate: vi.fn().mockResolvedValue({ executable: 'claude', version: '2.1.220' }) };
+        const store = { create: vi.fn().mockResolvedValue({ id: 'agent-id', name: 'reviewer' }) };
+        const runner = { run: vi.fn() };
+        const Service = api.ClaudePrintAgentService as new (options: unknown) => any;
+
+        await expect(new Service({ store, probe, runner }).create({ name: 'reviewer', cwd: '/project' }))
+            .resolves.toMatchObject({ id: 'agent-id' });
+        expect(probe.validate).toHaveBeenCalledOnce();
+        expect(store.create).toHaveBeenCalledWith({ name: 'reviewer', cwd: '/project' });
+        expect(runner.run).not.toHaveBeenCalled();
+    });
+
+    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 store = {
+            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().mockResolvedValue({}),
+        };
+        const runner = { run: vi.fn().mockImplementation(async (request) => {
+            await request.onSpawn({ pid: 42, startedAt: 'start' });
+            return { sessionId: 'session', result: 'answer', exitCode: 0 };
+        }) };
+        const Service = api.ClaudePrintAgentService as new (options: unknown) => any;
+        const service = new Service({ store, probe: { validate: vi.fn() }, runner, executable: 'fake-claude' });
+
+        await service.send('reviewer', 'first');
+        await service.send('id', 'later');
+
+        expect(runner.run.mock.calls[0][0]).toMatchObject({ prompt: 'first', firstRun: true, executable: 'fake-claude' });
+        expect(runner.run.mock.calls[1][0]).toMatchObject({ prompt: 'later', firstRun: false, executable: 'fake-claude' });
+        expect(store.recordProviderProcess).toHaveBeenCalledWith('id', 'one', { pid: 42, startedAt: 'start' });
+        expect(store.completeRun).toHaveBeenCalledWith('id', 'one', expect.objectContaining({
+            status: 'succeeded', exitCode: 0, sessionHealth: 'healthy',
+        }));
+    });
+});

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

@@ -0,0 +1,105 @@
+import { EventEmitter } from 'node:events';
+import { PassThrough, Writable } from 'node:stream';
+import { describe, expect, it, vi } from 'vitest';
+import type { PrintAgent } from '../../index.js';
+
+function agent(): PrintAgent {
+    return {
+        id: '11111111-1111-4111-8111-111111111111', name: 'reviewer', provider: 'claude', mode: 'print',
+        cwd: '/project', providerSessionId: '22222222-2222-4222-8222-222222222222', state: 'running',
+        sessionHealth: 'uninitialized', createdAt: '', updatedAt: '', lastActiveAt: null, lastResult: null,
+        activeRun: null,
+    };
+}
+
+function fakeSpawn(events: object[], exitCode = 0) {
+    const calls: unknown[][] = [];
+    const promptChunks: Buffer[] = [];
+    const child = new EventEmitter() as any;
+    child.pid = 4242;
+    child.stdout = new PassThrough();
+    child.stderr = new PassThrough();
+    child.stdin = new Writable({
+        write(chunk, _encoding, callback) { promptChunks.push(Buffer.from(chunk)); callback(); },
+        final(callback) {
+            for (const event of events) child.stdout.write(`${JSON.stringify(event)}\n`);
+            child.stdout.end();
+            queueMicrotask(() => child.emit('close', exitCode, null));
+            callback();
+        },
+    });
+    const spawn = vi.fn((...args: unknown[]) => { calls.push(args); return child; });
+    return { spawn, calls, promptChunks };
+}
+
+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: {
+            getIdentity: () => ({ pid: 4242, startedAt: 'provider-start' }),
+        } });
+
+        const result = await runner.run({
+            agent: agent(), prompt: 'secret prompt', executable: 'claude-test', firstRun: true,
+            onSpawn: async () => { expect(fixture.promptChunks).toHaveLength(0); persisted = true; },
+        });
+
+        expect(persisted).toBe(true);
+        expect(fixture.calls[0]).toEqual([
+            'claude-test',
+            ['-p', '--session-id', agent().providerSessionId, '--output-format', 'stream-json', '--verbose'],
+            expect.objectContaining({ cwd: '/project', shell: false, stdio: ['pipe', 'pipe', 'pipe'] }),
+        ]);
+        expect(JSON.stringify(fixture.calls)).not.toContain('secret prompt');
+        expect(Buffer.concat(fixture.promptChunks).toString()).toBe('secret prompt');
+        expect(result).toEqual({ sessionId: agent().providerSessionId, result: 'done', exitCode: 0 });
+    });
+
+    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: {
+            getIdentity: () => ({ pid: 4242, startedAt: 'provider-start' }),
+        } });
+
+        await expect(runner.run({
+            agent: agent(), prompt: 'followup', executable: 'claude', firstRun: false, onSpawn: vi.fn(),
+        })).rejects.toMatchObject({ code: 'CLAUDE_SESSION_MISMATCH' });
+        expect(fixture.calls[0]![1]).toEqual([
+            '-p', '--resume', agent().providerSessionId, '--output-format', 'stream-json', '--verbose',
+        ]);
+    });
+
+    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: {
+            getIdentity: () => ({ pid: 4242, startedAt: 'provider-start' }),
+        } });
+        fixture.spawn.mockImplementationOnce((...args: unknown[]) => {
+            const child = (fakeSpawn([], 1).spawn as any)(...args);
+            child.stdin = new Writable({
+                final(callback) {
+                    child.stderr.write('secret prompt echoed by provider');
+                    child.stderr.end();
+                    queueMicrotask(() => child.emit('close', 1, null));
+                    callback();
+                },
+            });
+            return child;
+        });
+
+        await expect(runner.run({
+            agent: agent(), prompt: 'secret prompt', firstRun: true, onSpawn: vi.fn(),
+        })).rejects.not.toThrow(/secret prompt/);
+    });
+});

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

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+
+describe('print-agent public domain', () => {
+    it('exports a classified busy error without exposing prompt data', async () => {
+        const api = await import('../../index.js') as Record<string, unknown>;
+
+        expect(api).toHaveProperty('PrintAgentBusyError');
+        const ErrorType = api.PrintAgentBusyError as new (agentId: string, name: string) => Error & {
+            code: string;
+            agentId: string;
+        };
+        const error = new ErrorType('agent-id', 'reviewer');
+
+        expect(error).toMatchObject({
+            name: 'PrintAgentBusyError',
+            code: 'PRINT_AGENT_BUSY',
+            agentId: 'agent-id',
+            message: 'Print agent "reviewer" is busy.',
+        });
+    });
+});

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

@@ -0,0 +1,192 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, describe, expect, it } from 'vitest';
+
+const tempDirs: string[] = [];
+
+afterEach(() => {
+    for (const dir of tempDirs.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+async function loadStore(): Promise<any> {
+    const api = await import('../../index.js') as Record<string, unknown>;
+    expect(api).toHaveProperty('PrintAgentStore');
+    return api.PrintAgentStore;
+}
+
+function fixture(): { root: string; cwd: string; filePath: string } {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'print-agent-store-'));
+    tempDirs.push(root);
+    const cwd = path.join(root, 'project');
+    fs.mkdirSync(cwd);
+    return { root, cwd, filePath: path.join(root, 'state', 'print-agents.json') };
+}
+
+describe('PrintAgentStore create/list/resolve', () => {
+    it('creates distinct durable identities with a canonical cwd and lists them', async () => {
+        const PrintAgentStore = await loadStore();
+        const { cwd, filePath } = fixture();
+        const store = new PrintAgentStore({ filePath, now: () => new Date('2026-08-07T09:00:00Z') });
+
+        const agent = await store.create({ name: 'reviewer', cwd });
+
+        expect(agent).toMatchObject({
+            name: 'reviewer',
+            provider: 'claude',
+            mode: 'print',
+            cwd: fs.realpathSync(cwd),
+            state: 'ready',
+            sessionHealth: 'uninitialized',
+            activeRun: null,
+        });
+        expect(agent.id).toMatch(/^[0-9a-f-]{36}$/);
+        expect(agent.providerSessionId).toMatch(/^[0-9a-f-]{36}$/);
+        expect(agent.id).not.toBe(agent.providerSessionId);
+        expect(await store.list()).toEqual([agent]);
+        expect(fs.statSync(filePath).mode & 0o777).toBe(0o600);
+    });
+
+    it('resolves exact ids and names and rejects duplicate names', async () => {
+        const PrintAgentStore = await loadStore();
+        const { cwd, filePath } = fixture();
+        const store = new PrintAgentStore({ filePath });
+        const agent = await store.create({ name: 'Reviewer', cwd });
+
+        expect(await store.resolve(agent.id)).toMatchObject({ id: agent.id });
+        expect(await store.resolve('reviewer')).toMatchObject({ id: agent.id });
+        expect(await store.resolve('view')).toBeNull();
+        await expect(store.create({ name: 'reviewer', cwd })).rejects.toMatchObject({
+            code: 'PRINT_AGENT_NAME_CONFLICT',
+        });
+    });
+
+    it('rejects missing cwd, malformed storage, and symlinked store targets', async () => {
+        const PrintAgentStore = await loadStore();
+        const { root, cwd, filePath } = fixture();
+        const store = new PrintAgentStore({ filePath });
+
+        await expect(store.create({ name: 'missing', cwd: path.join(root, 'missing') }))
+            .rejects.toMatchObject({ code: 'PRINT_AGENT_STORE' });
+
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, '{bad json', { mode: 0o600 });
+        await expect(store.list()).rejects.toMatchObject({ code: 'PRINT_AGENT_STORE' });
+
+        fs.rmSync(filePath);
+        const target = path.join(root, 'target.json');
+        fs.writeFileSync(target, JSON.stringify({ version: 1, agents: [] }));
+        fs.symlinkSync(target, filePath);
+        await expect(store.create({ name: 'unsafe', cwd })).rejects.toMatchObject({
+            code: 'PRINT_AGENT_STORE',
+        });
+    });
+
+    it('recovers an abandoned old mutation lock after a crash', async () => {
+        const PrintAgentStore = await loadStore();
+        const { cwd, filePath } = fixture();
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        const lockPath = `${filePath}.lock`;
+        fs.mkdirSync(lockPath);
+        const old = new Date(Date.now() - 60_000);
+        fs.utimesSync(lockPath, old, old);
+        const store = new PrintAgentStore({ filePath, mutationLockStaleMs: 10 });
+
+        await expect(store.create({ name: 'recovered', cwd })).resolves.toMatchObject({ name: 'recovered' });
+    });
+});
+
+describe('PrintAgentStore run ownership', () => {
+    it('fails fast when another exact owner is live and completes only for its token', async () => {
+        const PrintAgentStore = await loadStore();
+        const { cwd, filePath } = fixture();
+        const live = new Map<number, string>([[process.pid, 'owner-start']]);
+        const processInspector = { getIdentity: (pid: number) => {
+            const startedAt = live.get(pid);
+            return startedAt ? { pid, startedAt } : null;
+        } };
+        const store = new PrintAgentStore({ filePath, processInspector });
+        const agent = await store.create({ name: 'runner', cwd });
+
+        const acquired = await store.acquireRun(agent.id);
+        await expect(store.acquireRun(agent.id)).rejects.toMatchObject({ code: 'PRINT_AGENT_BUSY' });
+        await expect(store.completeRun(agent.id, 'wrong-token', {
+            status: 'succeeded', exitCode: 0, summary: 'done', sessionHealth: 'healthy',
+        })).rejects.toMatchObject({ code: 'PRINT_AGENT_STORE' });
+
+        const completed = await store.completeRun(agent.id, acquired.token, {
+            status: 'succeeded', exitCode: 0, summary: 'done', sessionHealth: 'healthy',
+        });
+        expect(completed).toMatchObject({ state: 'ready', sessionHealth: 'healthy', activeRun: null });
+    });
+
+    it('retains busy for a live provider then recovers a dead run without signaling it', async () => {
+        const PrintAgentStore = await loadStore();
+        const { cwd, filePath } = fixture();
+        const live = new Map<number, string>([[process.pid, 'owner-start'], [4242, 'provider-start']]);
+        const processInspector = { getIdentity: (pid: number) => {
+            const startedAt = live.get(pid);
+            return startedAt ? { pid, startedAt } : null;
+        } };
+        const first = new PrintAgentStore({ filePath, processInspector });
+        const agent = await first.create({ name: 'recoverable', cwd });
+        const run = await first.acquireRun(agent.id);
+        await first.recordProviderProcess(agent.id, run.token, { pid: 4242, startedAt: 'provider-start' });
+
+        live.delete(process.pid);
+        await expect(first.acquireRun(agent.id)).rejects.toMatchObject({ code: 'PRINT_AGENT_BUSY' });
+
+        live.delete(4242);
+        live.set(process.pid, 'replacement-owner-start');
+        const recovered = await first.acquireRun(agent.id);
+        expect(recovered.agent).toMatchObject({
+            state: 'running',
+            lastResult: { status: 'interrupted' },
+        });
+        await first.completeRun(agent.id, recovered.token, {
+            status: 'failed', exitCode: 1, summary: 'failed', sessionHealth: 'unknown',
+        });
+    });
+
+    it('reconciles an old incomplete lock to degraded during list', async () => {
+        const PrintAgentStore = await loadStore();
+        const { root, cwd, filePath } = fixture();
+        const live = new Map<number, string>([[process.pid, 'owner-start']]);
+        const store = new PrintAgentStore({ filePath, incompleteLockGraceMs: 10, processInspector: {
+            getIdentity: (pid: number) => {
+                const startedAt = live.get(pid);
+                return startedAt ? { pid, startedAt } : null;
+            },
+        } });
+        const agent = await store.create({ name: 'crashed', cwd });
+        await store.acquireRun(agent.id);
+        const lockPath = path.join(root, 'state', 'print-agent-locks', `${agent.id}.lock`);
+        fs.unlinkSync(path.join(lockPath, 'owner.json'));
+        const old = new Date(Date.now() - 1000);
+        fs.utimesSync(lockPath, old, old);
+        live.clear();
+
+        const listed = await store.list();
+
+        expect(listed[0]).toMatchObject({
+            state: 'degraded',
+            sessionHealth: 'unknown',
+            activeRun: null,
+            lastResult: { status: 'interrupted' },
+        });
+    });
+
+    it('rejects send acquisition when the bound cwd is replaced by a symlink', async () => {
+        const PrintAgentStore = await loadStore();
+        const { root, cwd, filePath } = fixture();
+        const store = new PrintAgentStore({ filePath });
+        const agent = await store.create({ name: 'bound', cwd });
+        const moved = path.join(root, 'moved-project');
+        const other = path.join(root, 'other-project');
+        fs.renameSync(cwd, moved);
+        fs.mkdirSync(other);
+        fs.symlinkSync(other, cwd);
+
+        await expect(store.acquireRun(agent.id)).rejects.toMatchObject({ code: 'PRINT_AGENT_STORE' });
+    });
+});