@soleri/core 9.5.0 → 9.6.0

package/src/__tests__/subagent/concurrency-manager.test.ts

@@ -0,0 +1,132 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { ConcurrencyManager } from '../../subagent/concurrency-manager.js';
+
+describe('ConcurrencyManager', () => {
+  let cm: ConcurrencyManager;
+
+  beforeEach(() => {
+    cm = new ConcurrencyManager();
+  });
+
+  it('acquire() resolves immediately when under the limit', async () => {
+    await cm.acquire('test', 3);
+    expect(cm.getActive('test')).toBe(1);
+  });
+
+  it('acquire() queues when at the limit', async () => {
+    // Fill all 2 slots
+    await cm.acquire('test', 2);
+    await cm.acquire('test', 2);
+    expect(cm.getActive('test')).toBe(2);
+
+    // Third acquire should queue
+    let resolved = false;
+    const pending = cm.acquire('test', 2).then(() => {
+      resolved = true;
+    });
+
+    // Give microtask queue a tick
+    await Promise.resolve();
+    expect(resolved).toBe(false);
+    expect(cm.getWaiting('test')).toBe(1);
+
+    // Release one slot to unblock
+    cm.release('test');
+    await pending;
+    expect(resolved).toBe(true);
+  });
+
+  it('release() unblocks the next waiter in FIFO order', async () => {
+    await cm.acquire('test', 1);
+
+    const order: number[] = [];
+    const p1 = cm.acquire('test', 1).then(() => order.push(1));
+    const p2 = cm.acquire('test', 1).then(() => order.push(2));
+
+    expect(cm.getWaiting('test')).toBe(2);
+
+    cm.release('test');
+    await p1;
+    cm.release('test');
+    await p2;
+
+    expect(order).toEqual([1, 2]);
+  });
+
+  it('getActive() returns correct count', async () => {
+    expect(cm.getActive('test')).toBe(0);
+    await cm.acquire('test', 5);
+    await cm.acquire('test', 5);
+    expect(cm.getActive('test')).toBe(2);
+  });
+
+  it('getWaiting() returns correct count', async () => {
+    await cm.acquire('test', 1);
+    expect(cm.getWaiting('test')).toBe(0);
+
+    // These will queue
+    cm.acquire('test', 1);
+    cm.acquire('test', 1);
+    await Promise.resolve();
+    expect(cm.getWaiting('test')).toBe(2);
+  });
+
+  it('reset() resolves all waiters and clears state', async () => {
+    await cm.acquire('test', 1);
+
+    let waiterResolved = false;
+    const pending = cm.acquire('test', 1).then(() => {
+      waiterResolved = true;
+    });
+
+    cm.reset();
+    await pending;
+    expect(waiterResolved).toBe(true);
+    expect(cm.getActive('test')).toBe(0);
+    expect(cm.getWaiting('test')).toBe(0);
+  });
+
+  it('multiple types are independent', async () => {
+    await cm.acquire('typeA', 1);
+    await cm.acquire('typeB', 1);
+
+    expect(cm.getActive('typeA')).toBe(1);
+    expect(cm.getActive('typeB')).toBe(1);
+
+    // typeA is at limit=1, but typeB should still be acquirable
+    let typeBResolved = false;
+    const pending = cm.acquire('typeB', 2).then(() => {
+      typeBResolved = true;
+    });
+    await pending;
+    expect(typeBResolved).toBe(true);
+    expect(cm.getActive('typeB')).toBe(2);
+  });
+
+  it('default maxConcurrent is 3', async () => {
+    // Acquire 3 without specifying max (uses default of 3)
+    await cm.acquire('test');
+    await cm.acquire('test');
+    await cm.acquire('test');
+    expect(cm.getActive('test')).toBe(3);
+
+    // Fourth should queue
+    let queued = false;
+    cm.acquire('test').then(() => {
+      queued = true;
+    });
+    await Promise.resolve();
+    expect(queued).toBe(false);
+    expect(cm.getWaiting('test')).toBe(1);
+  });
+
+  it('release() is a no-op for untracked types', () => {
+    // Should not throw
+    cm.release('nonexistent');
+    expect(cm.getActive('nonexistent')).toBe(0);
+  });
+
+  it('getActive() returns 0 for untracked types', () => {
+    expect(cm.getActive('unknown')).toBe(0);
+  });
+});

package/src/__tests__/subagent/dispatcher.test.ts

@@ -0,0 +1,195 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { SubagentDispatcher } from '../../subagent/dispatcher.js';
+import { RuntimeAdapterRegistry } from '../../adapters/registry.js';
+import type { RuntimeAdapter } from '../../adapters/types.js';
+import type { SubagentTask } from '../../subagent/types.js';
+
+function createMockRegistry() {
+  const registry = new RuntimeAdapterRegistry();
+  const mockAdapter: RuntimeAdapter = {
+    type: 'mock',
+    execute: vi.fn().mockResolvedValue({ exitCode: 0, summary: 'done' }),
+    testEnvironment: vi.fn().mockResolvedValue({ available: true }),
+  };
+  registry.register('mock', mockAdapter);
+  registry.setDefault('mock');
+  return { registry, mockAdapter };
+}
+
+function makeTask(overrides: Partial<SubagentTask> & { taskId: string }): SubagentTask {
+  return {
+    prompt: 'do something',
+    workspace: '/tmp/test',
+    ...overrides,
+  };
+}
+
+describe('SubagentDispatcher', () => {
+  let dispatcher: SubagentDispatcher;
+  let mockAdapter: RuntimeAdapter;
+
+  beforeEach(() => {
+    const { registry, mockAdapter: adapter } = createMockRegistry();
+    mockAdapter = adapter;
+    dispatcher = new SubagentDispatcher({ adapterRegistry: registry });
+  });
+
+  it('constructor accepts config with adapterRegistry', () => {
+    const { registry } = createMockRegistry();
+    const d = new SubagentDispatcher({ adapterRegistry: registry });
+    expect(d).toBeDefined();
+  });
+
+  it('dispatch() with empty tasks returns aggregate with 0 tasks', async () => {
+    const result = await dispatcher.dispatch([]);
+    expect(result.totalTasks).toBe(0);
+    expect(result.status).toBe('all-passed');
+    expect(result.results).toEqual([]);
+  });
+
+  it('dispatch() calls adapter.execute() for each task', async () => {
+    const tasks = [makeTask({ taskId: 'a' }), makeTask({ taskId: 'b' })];
+
+    await dispatcher.dispatch(tasks, { parallel: false });
+    expect(mockAdapter.execute).toHaveBeenCalledTimes(2);
+  });
+
+  it('dispatch() respects parallel=false option (sequential)', async () => {
+    const callOrder: string[] = [];
+    (mockAdapter.execute as ReturnType<typeof vi.fn>).mockImplementation(async (ctx) => {
+      callOrder.push(ctx.runId);
+      return { exitCode: 0, summary: 'ok' };
+    });
+
+    const tasks = [makeTask({ taskId: 'first' }), makeTask({ taskId: 'second' })];
+
+    await dispatcher.dispatch(tasks, { parallel: false });
+    expect(callOrder).toHaveLength(2);
+    // In sequential mode, first task should complete before second starts
+    expect(callOrder[0]).toContain('first');
+    expect(callOrder[1]).toContain('second');
+  });
+
+  it('dispatch() handles adapter failure gracefully', async () => {
+    (mockAdapter.execute as ReturnType<typeof vi.fn>).mockRejectedValueOnce(
+      new Error('Adapter crashed'),
+    );
+
+    const tasks = [makeTask({ taskId: 'fail-task' })];
+    const result = await dispatcher.dispatch(tasks);
+
+    expect(result.totalTasks).toBe(1);
+    expect(result.failed).toBe(1);
+    expect(result.results[0].error).toContain('Adapter crashed');
+  });
+
+  it('dispatch() claims and releases tasks', async () => {
+    const tasks = [makeTask({ taskId: 'claim-test' })];
+    await dispatcher.dispatch(tasks);
+
+    // After dispatch, the task should be released (available again)
+    // We verify by dispatching the same task again successfully
+    const result = await dispatcher.dispatch(tasks);
+    expect(result.completed).toBe(1);
+  });
+
+  it('dispatch() uses concurrency control in parallel mode', async () => {
+    let concurrentCount = 0;
+    let maxConcurrent = 0;
+
+    (mockAdapter.execute as ReturnType<typeof vi.fn>).mockImplementation(async () => {
+      concurrentCount++;
+      maxConcurrent = Math.max(maxConcurrent, concurrentCount);
+      await new Promise((resolve) => setTimeout(resolve, 50));
+      concurrentCount--;
+      return { exitCode: 0, summary: 'ok' };
+    });
+
+    const tasks = [
+      makeTask({ taskId: 'c1' }),
+      makeTask({ taskId: 'c2' }),
+      makeTask({ taskId: 'c3' }),
+      makeTask({ taskId: 'c4' }),
+      makeTask({ taskId: 'c5' }),
+    ];
+
+    await dispatcher.dispatch(tasks, { parallel: true, maxConcurrent: 2 });
+    // Max concurrent should not exceed 2
+    expect(maxConcurrent).toBeLessThanOrEqual(2);
+  });
+
+  it('dispatch() resolves dependencies correctly (task B depends on task A)', async () => {
+    const callOrder: string[] = [];
+    (mockAdapter.execute as ReturnType<typeof vi.fn>).mockImplementation(async (ctx) => {
+      callOrder.push(ctx.runId);
+      return { exitCode: 0, summary: 'ok' };
+    });
+
+    const tasks = [makeTask({ taskId: 'B', dependencies: ['A'] }), makeTask({ taskId: 'A' })];
+
+    await dispatcher.dispatch(tasks, { parallel: true });
+    // A should execute before B
+    const aIndex = callOrder.findIndex((r) => r.includes('-A-'));
+    const bIndex = callOrder.findIndex((r) => r.includes('-B-'));
+    expect(aIndex).toBeLessThan(bIndex);
+  });
+
+  it('dispatch() handles deadlocked dependencies', async () => {
+    const tasks = [
+      makeTask({ taskId: 'X', dependencies: ['Y'] }),
+      makeTask({ taskId: 'Y', dependencies: ['X'] }),
+    ];
+
+    const result = await dispatcher.dispatch(tasks, { parallel: true });
+    // Both tasks should fail due to unresolvable dependencies
+    expect(result.failed).toBe(2);
+    expect(result.results.every((r) => r.error?.includes('Unresolvable dependencies'))).toBe(true);
+  });
+
+  it('cleanup() clears all state', async () => {
+    const tasks = [makeTask({ taskId: 'cleanup-test' })];
+    await dispatcher.dispatch(tasks);
+
+    // cleanup should not throw
+    dispatcher.cleanup();
+  });
+
+  it('reapOrphans() returns orphaned results when processes are dead', () => {
+    // reapOrphans delegates to the internal OrphanReaper
+    // Without registering processes, it should return empty
+    const orphaned = dispatcher.reapOrphans();
+    expect(orphaned).toEqual([]);
+  });
+
+  it('dispatch() stops on first failure in sequential mode', async () => {
+    let callCount = 0;
+    (mockAdapter.execute as ReturnType<typeof vi.fn>).mockImplementation(async () => {
+      callCount++;
+      if (callCount === 1) {
+        return { exitCode: 1, summary: 'failed' };
+      }
+      return { exitCode: 0, summary: 'ok' };
+    });
+
+    const tasks = [makeTask({ taskId: 'first' }), makeTask({ taskId: 'second' })];
+
+    const result = await dispatcher.dispatch(tasks, { parallel: false });
+    // Only the first task should have been executed
+    expect(callCount).toBe(1);
+    expect(result.results).toHaveLength(1);
+    expect(result.failed).toBe(1);
+  });
+
+  it('dispatch() invokes onTaskUpdate callback', async () => {
+    const updates: Array<[string, string]> = [];
+
+    const tasks = [makeTask({ taskId: 'cb-test' })];
+    await dispatcher.dispatch(tasks, {
+      parallel: false,
+      onTaskUpdate: (taskId, status) => updates.push([taskId, status]),
+    });
+
+    expect(updates.length).toBeGreaterThanOrEqual(1);
+    expect(updates[0][0]).toBe('cb-test');
+  });
+});

package/src/__tests__/subagent/orphan-reaper.test.ts

@@ -0,0 +1,141 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { OrphanReaper } from '../../subagent/orphan-reaper.js';
+
+describe('OrphanReaper', () => {
+  let killSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    killSpy = vi.spyOn(process, 'kill');
+  });
+
+  afterEach(() => {
+    killSpy.mockRestore();
+  });
+
+  it('register() tracks a process', () => {
+    const reaper = new OrphanReaper();
+    reaper.register(1234, 'task-1');
+    expect(reaper.isTracked(1234)).toBe(true);
+    expect(reaper.listTracked()).toHaveLength(1);
+    expect(reaper.listTracked()[0].taskId).toBe('task-1');
+  });
+
+  it('unregister() stops tracking a process', () => {
+    const reaper = new OrphanReaper();
+    reaper.register(1234, 'task-1');
+    reaper.unregister(1234);
+    expect(reaper.isTracked(1234)).toBe(false);
+    expect(reaper.listTracked()).toHaveLength(0);
+  });
+
+  it('reap() returns empty when all processes are alive', () => {
+    // process.kill(pid, 0) succeeds = process alive
+    killSpy.mockImplementation(() => true);
+
+    const reaper = new OrphanReaper();
+    reaper.register(1234, 'task-1');
+    reaper.register(5678, 'task-2');
+
+    const reaped = reaper.reap();
+    expect(reaped).toHaveLength(0);
+    expect(reaper.listTracked()).toHaveLength(2);
+  });
+
+  it('reap() detects dead processes via ESRCH', () => {
+    killSpy.mockImplementation((_pid: number, _signal?: number) => {
+      const err = new Error('No such process') as NodeJS.ErrnoException;
+      err.code = 'ESRCH';
+      throw err;
+    });
+
+    const reaper = new OrphanReaper();
+    reaper.register(1234, 'task-1');
+
+    const reaped = reaper.reap();
+    expect(reaped).toHaveLength(1);
+    expect(reaped[0].taskId).toBe('task-1');
+    expect(reaped[0].pid).toBe(1234);
+    // Dead process should be removed from tracking
+    expect(reaper.isTracked(1234)).toBe(false);
+  });
+
+  it('reap() calls onOrphan callback for dead processes', () => {
+    killSpy.mockImplementation(() => {
+      const err = new Error('No such process') as NodeJS.ErrnoException;
+      err.code = 'ESRCH';
+      throw err;
+    });
+
+    const onOrphan = vi.fn();
+    const reaper = new OrphanReaper(onOrphan);
+    reaper.register(1234, 'task-1');
+
+    reaper.reap();
+    expect(onOrphan).toHaveBeenCalledWith('task-1', 1234);
+  });
+
+  it('reap() treats EPERM as alive (process exists but no permission)', () => {
+    killSpy.mockImplementation(() => {
+      const err = new Error('Operation not permitted') as NodeJS.ErrnoException;
+      err.code = 'EPERM';
+      throw err;
+    });
+
+    const reaper = new OrphanReaper();
+    reaper.register(1234, 'task-1');
+
+    const reaped = reaper.reap();
+    expect(reaped).toHaveLength(0);
+    expect(reaper.isTracked(1234)).toBe(true);
+  });
+
+  it('listTracked() returns all tracked processes', () => {
+    const reaper = new OrphanReaper();
+    reaper.register(100, 'task-a');
+    reaper.register(200, 'task-b');
+    reaper.register(300, 'task-c');
+
+    const tracked = reaper.listTracked();
+    expect(tracked).toHaveLength(3);
+    expect(tracked.map((t) => t.pid).sort()).toEqual([100, 200, 300]);
+  });
+
+  it('isTracked() returns correct boolean', () => {
+    const reaper = new OrphanReaper();
+    expect(reaper.isTracked(999)).toBe(false);
+    reaper.register(999, 'task-x');
+    expect(reaper.isTracked(999)).toBe(true);
+  });
+
+  it('clear() removes all tracked processes', () => {
+    const reaper = new OrphanReaper();
+    reaper.register(100, 'task-a');
+    reaper.register(200, 'task-b');
+
+    reaper.clear();
+    expect(reaper.listTracked()).toHaveLength(0);
+    expect(reaper.isTracked(100)).toBe(false);
+    expect(reaper.isTracked(200)).toBe(false);
+  });
+
+  it('reap() handles mixed alive and dead processes', () => {
+    killSpy.mockImplementation((pid: number, _signal?: number) => {
+      if (pid === 1234) {
+        return true; // alive
+      }
+      const err = new Error('No such process') as NodeJS.ErrnoException;
+      err.code = 'ESRCH';
+      throw err;
+    });
+
+    const reaper = new OrphanReaper();
+    reaper.register(1234, 'task-alive');
+    reaper.register(5678, 'task-dead');
+
+    const reaped = reaper.reap();
+    expect(reaped).toHaveLength(1);
+    expect(reaped[0].taskId).toBe('task-dead');
+    expect(reaper.isTracked(1234)).toBe(true);
+    expect(reaper.isTracked(5678)).toBe(false);
+  });
+});

package/src/__tests__/subagent/result-aggregator.test.ts

@@ -0,0 +1,141 @@
+import { describe, it, expect } from 'vitest';
+import { aggregate } from '../../subagent/result-aggregator.js';
+import type { SubagentResult } from '../../subagent/types.js';
+
+function makeResult(overrides: Partial<SubagentResult> & { taskId: string }): SubagentResult {
+  return {
+    status: overrides.exitCode === 0 ? 'completed' : 'failed',
+    exitCode: 0,
+    durationMs: 100,
+    ...overrides,
+  };
+}
+
+describe('aggregate()', () => {
+  it('returns all-passed for all exitCode 0', () => {
+    const results: SubagentResult[] = [
+      makeResult({ taskId: 'a', exitCode: 0 }),
+      makeResult({ taskId: 'b', exitCode: 0 }),
+    ];
+    const agg = aggregate(results);
+    expect(agg.status).toBe('all-passed');
+    expect(agg.completed).toBe(2);
+    expect(agg.failed).toBe(0);
+  });
+
+  it('returns all-failed for all non-zero exitCodes', () => {
+    const results: SubagentResult[] = [
+      makeResult({ taskId: 'a', exitCode: 1, status: 'failed' }),
+      makeResult({ taskId: 'b', exitCode: 1, status: 'failed' }),
+    ];
+    const agg = aggregate(results);
+    expect(agg.status).toBe('all-failed');
+    expect(agg.completed).toBe(0);
+    expect(agg.failed).toBe(2);
+  });
+
+  it('returns partial for mixed results', () => {
+    const results: SubagentResult[] = [
+      makeResult({ taskId: 'a', exitCode: 0 }),
+      makeResult({ taskId: 'b', exitCode: 1, status: 'failed' }),
+    ];
+    const agg = aggregate(results);
+    expect(agg.status).toBe('partial');
+    expect(agg.completed).toBe(1);
+    expect(agg.failed).toBe(1);
+  });
+
+  it('sums token usage across results', () => {
+    const results: SubagentResult[] = [
+      makeResult({
+        taskId: 'a',
+        exitCode: 0,
+        usage: { inputTokens: 100, outputTokens: 50, totalTokens: 150 },
+      }),
+      makeResult({
+        taskId: 'b',
+        exitCode: 0,
+        usage: { inputTokens: 200, outputTokens: 75, totalTokens: 275 },
+      }),
+    ];
+    const agg = aggregate(results);
+    expect(agg.totalUsage.inputTokens).toBe(300);
+    expect(agg.totalUsage.outputTokens).toBe(125);
+    expect(agg.totalUsage.totalTokens).toBe(425);
+  });
+
+  it('handles results with no usage field', () => {
+    const results: SubagentResult[] = [
+      makeResult({ taskId: 'a', exitCode: 0 }),
+      makeResult({
+        taskId: 'b',
+        exitCode: 0,
+        usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 },
+      }),
+    ];
+    const agg = aggregate(results);
+    expect(agg.totalUsage.inputTokens).toBe(10);
+    expect(agg.totalUsage.outputTokens).toBe(5);
+    expect(agg.totalUsage.totalTokens).toBe(15);
+  });
+
+  it('deduplicates filesChanged', () => {
+    const results: SubagentResult[] = [
+      makeResult({ taskId: 'a', exitCode: 0, filesChanged: ['file1.ts', 'file2.ts'] }),
+      makeResult({ taskId: 'b', exitCode: 0, filesChanged: ['file2.ts', 'file3.ts'] }),
+    ];
+    const agg = aggregate(results);
+    expect(agg.filesChanged.sort()).toEqual(['file1.ts', 'file2.ts', 'file3.ts']);
+  });
+
+  it('handles empty results array', () => {
+    const agg = aggregate([]);
+    expect(agg.status).toBe('all-passed');
+    expect(agg.totalTasks).toBe(0);
+    expect(agg.completed).toBe(0);
+    expect(agg.failed).toBe(0);
+    expect(agg.filesChanged).toEqual([]);
+    expect(agg.combinedSummary).toBe('');
+    expect(agg.durationMs).toBe(0);
+    expect(agg.results).toEqual([]);
+  });
+
+  it('builds combinedSummary with taskId prefixes', () => {
+    const results: SubagentResult[] = [
+      makeResult({ taskId: 'task-1', exitCode: 0, summary: 'Fixed the bug' }),
+      makeResult({ taskId: 'task-2', exitCode: 0, summary: 'Added tests' }),
+    ];
+    const agg = aggregate(results);
+    expect(agg.combinedSummary).toContain('[task-1] Fixed the bug');
+    expect(agg.combinedSummary).toContain('[task-2] Added tests');
+  });
+
+  it('skips tasks without summary in combinedSummary', () => {
+    const results: SubagentResult[] = [
+      makeResult({ taskId: 'task-1', exitCode: 0, summary: 'Done' }),
+      makeResult({ taskId: 'task-2', exitCode: 0 }),
+    ];
+    const agg = aggregate(results);
+    expect(agg.combinedSummary).toBe('[task-1] Done');
+  });
+
+  it('uses max duration for durationMs', () => {
+    const results: SubagentResult[] = [
+      makeResult({ taskId: 'a', exitCode: 0, durationMs: 100 }),
+      makeResult({ taskId: 'b', exitCode: 0, durationMs: 500 }),
+      makeResult({ taskId: 'c', exitCode: 0, durationMs: 250 }),
+    ];
+    const agg = aggregate(results);
+    expect(agg.durationMs).toBe(500);
+  });
+
+  it('totalTasks matches the input count', () => {
+    const results: SubagentResult[] = [
+      makeResult({ taskId: 'a', exitCode: 0 }),
+      makeResult({ taskId: 'b', exitCode: 1, status: 'failed' }),
+      makeResult({ taskId: 'c', exitCode: 0 }),
+    ];
+    const agg = aggregate(results);
+    expect(agg.totalTasks).toBe(3);
+  });
+});

package/src/__tests__/subagent/task-checkout.test.ts

@@ -0,0 +1,86 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { TaskCheckout } from '../../subagent/task-checkout.js';
+
+describe('TaskCheckout', () => {
+  let checkout: TaskCheckout;
+
+  beforeEach(() => {
+    checkout = new TaskCheckout();
+  });
+
+  it('claim() returns true for an unclaimed task', () => {
+    expect(checkout.claim('task-1', 'agent-a')).toBe(true);
+  });
+
+  it('claim() returns false when a different claimer tries the same task', () => {
+    checkout.claim('task-1', 'agent-a');
+    expect(checkout.claim('task-1', 'agent-b')).toBe(false);
+  });
+
+  it('claim() returns true for the same claimer (idempotent)', () => {
+    checkout.claim('task-1', 'agent-a');
+    expect(checkout.claim('task-1', 'agent-a')).toBe(true);
+  });
+
+  it('claim() stores claimerId and taskId in ClaimInfo', () => {
+    checkout.claim('task-1', 'agent-a');
+    const info = checkout.getClaimer('task-1');
+    expect(info).toBeDefined();
+    expect(info!.taskId).toBe('task-1');
+    expect(info!.claimerId).toBe('agent-a');
+    expect(info!.claimedAt).toBeGreaterThan(0);
+  });
+
+  it('release() returns true for a claimed task', () => {
+    checkout.claim('task-1', 'agent-a');
+    expect(checkout.release('task-1')).toBe(true);
+  });
+
+  it('release() returns false for an unclaimed task', () => {
+    expect(checkout.release('task-1')).toBe(false);
+  });
+
+  it('getClaimer() returns ClaimInfo for a claimed task', () => {
+    checkout.claim('task-1', 'agent-a');
+    const info = checkout.getClaimer('task-1');
+    expect(info).toBeDefined();
+    expect(info!.claimerId).toBe('agent-a');
+  });
+
+  it('getClaimer() returns undefined for an unclaimed task', () => {
+    expect(checkout.getClaimer('task-1')).toBeUndefined();
+  });
+
+  it('isAvailable() returns true for an unclaimed task', () => {
+    expect(checkout.isAvailable('task-1')).toBe(true);
+  });
+
+  it('isAvailable() returns false for a claimed task', () => {
+    checkout.claim('task-1', 'agent-a');
+    expect(checkout.isAvailable('task-1')).toBe(false);
+  });
+
+  it('listClaimed() returns all active claims', () => {
+    checkout.claim('task-1', 'agent-a');
+    checkout.claim('task-2', 'agent-b');
+    const claims = checkout.listClaimed();
+    expect(claims).toHaveLength(2);
+    expect(claims.map((c) => c.taskId).sort()).toEqual(['task-1', 'task-2']);
+  });
+
+  it('releaseAll() clears all claims', () => {
+    checkout.claim('task-1', 'agent-a');
+    checkout.claim('task-2', 'agent-b');
+    checkout.releaseAll();
+    expect(checkout.listClaimed()).toHaveLength(0);
+    expect(checkout.isAvailable('task-1')).toBe(true);
+    expect(checkout.isAvailable('task-2')).toBe(true);
+  });
+
+  it('release() makes the task available for a new claimer', () => {
+    checkout.claim('task-1', 'agent-a');
+    checkout.release('task-1');
+    expect(checkout.claim('task-1', 'agent-b')).toBe(true);
+    expect(checkout.getClaimer('task-1')!.claimerId).toBe('agent-b');
+  });
+});