@zooid/core 0.7.0

package/src/acp-registry.test.ts

@@ -0,0 +1,217 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { EventEmitter } from 'node:events'
+import { Readable, Writable } from 'node:stream'
+import type { AcpRuntime, AcpSpawnSpec } from './acp-types.js'
+
+class FakeChild extends EventEmitter {
+  stdout = new Readable({ read() {} })
+  stdin = new Writable({ write(_c, _e, cb) { cb() } })
+  stderr = new Readable({ read() {} })
+  pid = 1
+  kill = vi.fn(() => true)
+}
+
+class StubRuntime implements AcpRuntime {
+  spawn = vi.fn((_: AcpSpawnSpec) => new FakeChild() as unknown as ReturnType<AcpRuntime['spawn']>)
+}
+
+vi.mock('@zooid/acp-client', async (orig) => {
+  const real = (await orig()) as Record<string, unknown>
+  return {
+    ...real,
+    AcpClient: vi.fn().mockImplementation(() => ({
+      start: vi.fn().mockResolvedValue(undefined),
+      prompt: vi.fn().mockResolvedValue({ stopReason: 'end_turn' }),
+      stop: vi.fn().mockResolvedValue(undefined),
+    })),
+  }
+})
+
+const { AcpAgentRegistry } = await import('./acp-registry.js')
+
+describe('AcpAgentRegistry', () => {
+  let runtime: StubRuntime
+  let registry: InstanceType<typeof AcpAgentRegistry>
+
+  beforeEach(async () => {
+    const { AcpClient } = (await import('@zooid/acp-client')) as unknown as {
+      AcpClient: ReturnType<typeof vi.fn>
+    }
+    AcpClient.mockClear()
+    runtime = new StubRuntime()
+    registry = new AcpAgentRegistry({
+      runtime,
+      agents: {
+        triage: {
+          name: 'triage',
+          workdir: '.',
+          hooks: {},
+          acp: { preset: 'claude' },
+          approval_timeout_ms: 0,
+        },
+        builder: {
+          name: 'builder',
+          workdir: '.',
+          hooks: {},
+          acp: { command: 'opencode', args: ['acp'] },
+          approval_timeout_ms: 0,
+        },
+      },
+      env: { triage: { ANTHROPIC_API_KEY: 'sk-test' } },
+    })
+  })
+
+  it('throws on prompt() for an unknown agent', async () => {
+    await expect(
+      registry.prompt('nope', { threadId: 't', content: [] }),
+    ).rejects.toThrow(/unknown agent/i)
+  })
+
+  it('hasAgent reflects config keys', () => {
+    expect(registry.hasAgent('triage')).toBe(true)
+    expect(registry.hasAgent('nope')).toBe(false)
+  })
+
+  it('lazily starts a client on first prompt', async () => {
+    const { AcpClient } = (await import('@zooid/acp-client')) as unknown as {
+      AcpClient: ReturnType<typeof vi.fn>
+    }
+    expect(AcpClient).not.toHaveBeenCalled()
+    await registry.prompt('triage', { threadId: 't1', content: [] })
+    expect(AcpClient).toHaveBeenCalledTimes(1)
+  })
+
+  it('reuses the same client across prompts (long-lived)', async () => {
+    const { AcpClient } = (await import('@zooid/acp-client')) as unknown as {
+      AcpClient: ReturnType<typeof vi.fn>
+    }
+    await registry.prompt('triage', { threadId: 't1', content: [] })
+    await registry.prompt('triage', { threadId: 't2', content: [] })
+    expect(AcpClient).toHaveBeenCalledTimes(1)
+  })
+
+  it('keeps clients per-agent isolated', async () => {
+    const { AcpClient } = (await import('@zooid/acp-client')) as unknown as {
+      AcpClient: ReturnType<typeof vi.fn>
+    }
+    await registry.prompt('triage', { threadId: 't', content: [] })
+    await registry.prompt('builder', { threadId: 't', content: [] })
+    expect(AcpClient).toHaveBeenCalledTimes(2)
+  })
+
+  it('passes preset → AcpClient via @zooid/acp-client preset registry', async () => {
+    const { AcpClient } = (await import('@zooid/acp-client')) as unknown as {
+      AcpClient: ReturnType<typeof vi.fn>
+    }
+    await registry.prompt('triage', { threadId: 't', content: [] })
+    const opts = AcpClient.mock.calls[0][0]
+    expect(opts.agent.command).toBe('npx')
+    expect(opts.agent.args).toEqual(['-y', '@agentclientprotocol/claude-agent-acp'])
+  })
+
+  it('passes explicit command/args through', async () => {
+    const { AcpClient } = (await import('@zooid/acp-client')) as unknown as {
+      AcpClient: ReturnType<typeof vi.fn>
+    }
+    await registry.prompt('builder', { threadId: 't', content: [] })
+    const opts = AcpClient.mock.calls[0][0]
+    expect(opts.agent.command).toBe('opencode')
+    expect(opts.agent.args).toEqual(['acp'])
+  })
+
+  it('passes per-agent env into AcpClient.agent.env', async () => {
+    const { AcpClient } = (await import('@zooid/acp-client')) as unknown as {
+      AcpClient: ReturnType<typeof vi.fn>
+    }
+    await registry.prompt('triage', { threadId: 't', content: [] })
+    const opts = AcpClient.mock.calls[0][0]
+    expect(opts.agent.env).toMatchObject({ ANTHROPIC_API_KEY: 'sk-test' })
+  })
+
+  it('threads the AcpRuntime into AcpClient', async () => {
+    const { AcpClient } = (await import('@zooid/acp-client')) as unknown as {
+      AcpClient: ReturnType<typeof vi.fn>
+    }
+    await registry.prompt('triage', { threadId: 't', content: [] })
+    const opts = AcpClient.mock.calls[0][0]
+    expect(opts.runtime).toBe(runtime)
+  })
+
+  it('stopAll() invokes stop on every started client', async () => {
+    const { AcpClient } = (await import('@zooid/acp-client')) as unknown as {
+      AcpClient: ReturnType<typeof vi.fn>
+    }
+    await registry.prompt('triage', { threadId: 't', content: [] })
+    await registry.stopAll()
+    const inst = AcpClient.mock.results[0].value as { stop: ReturnType<typeof vi.fn> }
+    expect(inst.stop).toHaveBeenCalled()
+  })
+})
+
+describe('AcpAgentRegistry.cancelSession', () => {
+  it('calls cancel on the underlying AcpClient and ApprovalCorrelator.cancelSession', async () => {
+    const correlator = {
+      register: vi.fn(),
+      resolve: vi.fn(),
+      cancelSession: vi.fn(),
+      listPending: vi.fn(() => []),
+      on: vi.fn(),
+      emit: vi.fn(),
+    } as unknown as import('./approval-correlator.js').ApprovalCorrelator
+    const registry = new AcpAgentRegistry({
+      runtime: { spawn: vi.fn() } as never,
+      agents: { architect: { acp: { command: 'noop' } } as never },
+      approvals: correlator,
+    })
+    const fakeClient = { cancel: vi.fn(async () => {}), stop: vi.fn(async () => {}) }
+    ;(registry as unknown as { clients: Map<string, typeof fakeClient> }).clients.set(
+      'architect',
+      fakeClient,
+    )
+    await registry.cancelSession('architect', 'sess-xyz')
+    expect(fakeClient.cancel).toHaveBeenCalledWith('sess-xyz')
+    expect((correlator as unknown as { cancelSession: ReturnType<typeof vi.fn> }).cancelSession).toHaveBeenCalledWith(
+      'sess-xyz',
+    )
+  })
+
+  it('is a no-op for an unknown agent', async () => {
+    const correlator = {
+      register: vi.fn(),
+      resolve: vi.fn(),
+      cancelSession: vi.fn(),
+      listPending: vi.fn(() => []),
+      on: vi.fn(),
+      emit: vi.fn(),
+    } as unknown as import('./approval-correlator.js').ApprovalCorrelator
+    const registry = new AcpAgentRegistry({
+      runtime: { spawn: vi.fn() } as never,
+      agents: {},
+      approvals: correlator,
+    })
+    await expect(registry.cancelSession('ghost', 'sess-xyz')).resolves.toBeUndefined()
+    expect(
+      (correlator as unknown as { cancelSession: ReturnType<typeof vi.fn> }).cancelSession,
+    ).not.toHaveBeenCalled()
+  })
+
+  it('cancels pending approvals even when no client has been spawned yet', async () => {
+    const correlator = {
+      register: vi.fn(),
+      resolve: vi.fn(),
+      cancelSession: vi.fn(),
+      listPending: vi.fn(() => []),
+      on: vi.fn(),
+      emit: vi.fn(),
+    } as unknown as import('./approval-correlator.js').ApprovalCorrelator
+    const registry = new AcpAgentRegistry({
+      runtime: { spawn: vi.fn() } as never,
+      agents: { architect: { acp: { command: 'noop' } } as never },
+      approvals: correlator,
+    })
+    await registry.cancelSession('architect', 'sess-xyz')
+    expect(
+      (correlator as unknown as { cancelSession: ReturnType<typeof vi.fn> }).cancelSession,
+    ).toHaveBeenCalledWith('sess-xyz')
+  })
+})

package/src/acp-registry.ts

@@ -0,0 +1,235 @@
+import { join } from 'node:path'
+import {
+  AcpClient,
+  resolvePreset,
+  type AgentEvent,
+  type ApprovalDecision,
+  type ApprovalRequest,
+  type PromptInput,
+  type PromptResult,
+  type TapEvent,
+} from '@zooid/acp-client'
+import type { AcpAgentSpec, AcpRuntime } from './acp-types.js'
+import type { AgentConfig } from './types.js'
+import type {
+  ApprovalCorrelator,
+  RegisteredApproval,
+} from './approval-correlator.js'
+
+export type AcpRegistryEventHandler = (
+  agentName: string,
+  event: AgentEvent,
+) => void
+export type AcpRegistryApprovalHandler = (
+  agentName: string,
+  req: ApprovalRequest,
+) => Promise<ApprovalDecision>
+
+/**
+ * Daemon-side surface of the ACP agent fleet. The transport (HTTP) consumes
+ * this; the CLI builds it via `buildAcpRegistry`. Long-lived: one
+ * `AcpClient` per agent, kept alive across prompts.
+ */
+export interface AcpRegistry {
+  hasAgent(name: string): boolean
+  /** Whether an agent has a transport-context provider attached. */
+  hasContextSpawn(name: string): boolean
+  /** Per-agent approval timeout from zooid.yaml. 0 means no timeout. */
+  getApprovalTimeoutMs(name: string): number
+  ensureSession(name: string, threadId: string, channelId?: string): Promise<string>
+  /** Drop the in-memory session for (agent, threadId). Next prompt re-creates one. */
+  endSession(name: string, threadId: string): void
+  prompt(name: string, input: PromptInput): Promise<PromptResult>
+  /**
+   * Cancel an in-flight prompt for (agent, sessionId). Sends `session/cancel`
+   * via the underlying AcpClient and resolves any pending approvals with
+   * `decision: 'cancel'`. Idempotent.
+   */
+  cancelSession(name: string, sessionId: string): Promise<void>
+  stopAll(): Promise<void>
+  /** Set by the transport. Receives every ACP event from any agent. */
+  onEvent: AcpRegistryEventHandler
+  /** Set by the transport. Resolves permission requests. */
+  onApprovalRequest: AcpRegistryApprovalHandler
+}
+
+export interface AcpAgentRegistryOptions {
+  runtime: AcpRuntime
+  agents: Record<string, AgentConfig>
+  /** Per-agent env passed to each `AcpClient`'s spawn spec. */
+  env?: Record<string, Record<string, string>>
+  /** Per-agent container image. Used by DockerAcpRuntime; ignored by LocalAcpRuntime. */
+  image?: Record<string, string | undefined>
+  /** Initial event handler (the transport may overwrite at app creation). */
+  onEvent?: AcpRegistryEventHandler
+  /** Initial approval handler (the transport may overwrite at app creation). */
+  onApprovalRequest?: AcpRegistryApprovalHandler
+  /**
+   * Optional correlator: when set, the registry's default
+   * `onApprovalRequest` registers each request on the correlator (with the
+   * agent's `approval_timeout_ms`) and returns the registered handle's
+   * `decisionPromise`. Transports listen on the correlator's `'registered'`
+   * + `'timeout'` events to drive the SSE wire and accept HTTP decisions.
+   */
+  approvals?: ApprovalCorrelator
+  /** Called whenever the correlator-backed handler registers an approval. */
+  onApprovalRegistered?: (approval: RegisteredApproval) => void
+  /**
+   * Optional observability tap. Forwarded to each AcpClient so the
+   * unfiltered ACP protocol stream + turn-boundary events are visible to
+   * the host (e.g. the dev CLI capturing them to disk).
+   */
+  onTap?: (agentName: string, event: TapEvent) => void
+  /**
+   * Root directory under which each agent gets a per-agent state dir
+   * (`<agentsDir>/<agentName>/`). Used by the AcpClient session store to
+   * persist ACP `sessionId`s across daemon restarts. Optional: when unset,
+   * session continuity across restarts is disabled.
+   */
+  agentsDir?: string
+  /**
+   * Per-agent factory that returns a `mcpServers[]` entry for the
+   * `zooid-context` MCP server. Forwarded to each AcpClient. Agents bound to
+   * transports without a context provider (e.g. HTTP) have no entry here.
+   */
+  contextSpawns?: Record<string, ContextSpawnFactory | undefined>
+}
+
+export type ContextSpawnFactory = (
+  threadId: string,
+  channelId?: string,
+) => Promise<{
+  name: 'zooid-context'
+  command: string
+  args: string[]
+  env: Array<{ name: string; value: string }>
+}>
+
+export class AcpAgentRegistry implements AcpRegistry {
+  readonly opts: AcpAgentRegistryOptions
+  private readonly clients = new Map<string, AcpClient>()
+
+  onEvent: AcpRegistryEventHandler
+  onApprovalRequest: AcpRegistryApprovalHandler
+
+  constructor(opts: AcpAgentRegistryOptions) {
+    this.opts = opts
+    this.onEvent = opts.onEvent ?? (() => {})
+    if (opts.onApprovalRequest) {
+      this.onApprovalRequest = opts.onApprovalRequest
+    } else if (opts.approvals) {
+      const correlator = opts.approvals
+      this.onApprovalRequest = async (name, req) => {
+        const cfg = this.opts.agents[name]
+        const handle = correlator.register(name, req.sessionId, req, {
+          timeoutMs: cfg?.approval_timeout_ms ?? 0,
+        })
+        this.opts.onApprovalRegistered?.(handle)
+        return handle.decisionPromise
+      }
+    } else {
+      this.onApprovalRequest = async () => ({ decision: 'cancel' })
+    }
+  }
+
+  hasAgent(name: string): boolean {
+    return Object.prototype.hasOwnProperty.call(this.opts.agents, name)
+  }
+
+  hasContextSpawn(name: string): boolean {
+    return Boolean(this.opts.contextSpawns?.[name])
+  }
+
+  resolveSpawnEnv(name: string): Record<string, string> {
+    return this.opts.env?.[name] ?? {}
+  }
+
+  resolveSpawnImage(name: string): string | undefined {
+    return this.opts.image?.[name]
+  }
+
+  getApprovalTimeoutMs(name: string): number {
+    return this.opts.agents[name]?.approval_timeout_ms ?? 0
+  }
+
+  async ensureSession(name: string, threadId: string, channelId?: string): Promise<string> {
+    if (!this.hasAgent(name)) throw new Error(`unknown agent: ${name}`)
+    const client = await this.ensureClient(name)
+    return client.ensureSession(threadId, channelId)
+  }
+
+  endSession(name: string, threadId: string): void {
+    if (!this.hasAgent(name)) return
+    const client = this.clients.get(name)
+    client?.endSession(threadId)
+  }
+
+  async cancelSession(name: string, sessionId: string): Promise<void> {
+    if (!this.hasAgent(name)) return
+    const client = this.clients.get(name)
+    // Always nudge the correlator first so any pending approvals resolve with
+    // 'cancel' regardless of whether the client is alive or already stopped.
+    this.opts.approvals?.cancelSession(sessionId)
+    if (!client) return
+    try {
+      await client.cancel(sessionId)
+    } catch (err) {
+      // ACP cancel is a notification; failures here are typically transport
+      // errors after the agent has already exited.
+      console.warn(`[acp:${name}] cancel(${sessionId}) failed:`, err)
+    }
+  }
+
+  async prompt(name: string, input: PromptInput): Promise<PromptResult> {
+    if (!this.hasAgent(name)) throw new Error(`unknown agent: ${name}`)
+    const client = await this.ensureClient(name)
+    return client.prompt(input)
+  }
+
+  async stopAll(): Promise<void> {
+    await Promise.allSettled(
+      [...this.clients.values()].map((c) => c.stop()),
+    )
+    this.clients.clear()
+  }
+
+  private async ensureClient(name: string): Promise<AcpClient> {
+    const existing = this.clients.get(name)
+    if (existing) return existing
+    const cfg = this.opts.agents[name]
+    if (!cfg.acp) throw new Error(`agents.${name}: missing acp block`)
+    const spawn = resolveAcpAgentSpec(cfg.acp)
+    const client = new AcpClient({
+      agent: {
+        id: name,
+        command: spawn.command,
+        args: spawn.args,
+        env: this.opts.env?.[name],
+        cwd: cfg.workdir,
+        image: this.opts.image?.[name],
+      },
+      agentDataDir: this.opts.agentsDir ? join(this.opts.agentsDir, name) : undefined,
+      runtime: this.opts.runtime,
+      onEvent: (e) => this.onEvent(name, e),
+      onApprovalRequest: (req) => this.onApprovalRequest(name, req),
+      onTap: this.opts.onTap ? (e) => this.opts.onTap!(name, e) : undefined,
+      contextSpawn: this.opts.contextSpawns?.[name],
+    })
+    await client.start()
+    this.clients.set(name, client)
+    return client
+  }
+}
+
+export function resolveAcpAgentSpec(spec: AcpAgentSpec): {
+  command: string
+  args: string[]
+} {
+  if ('preset' in spec && spec.preset) {
+    return resolvePreset(spec.preset, { model: spec.model })
+  }
+  if ('command' in spec && spec.command) {
+    return { command: spec.command, args: spec.args ?? [] }
+  }
+  throw new Error('AcpAgentSpec: must specify either preset or command')
+}

package/src/acp-types.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expectTypeOf } from 'vitest'
+import type { ChildProcess } from 'node:child_process'
+import type {
+  AcpAgentSpec,
+  AcpMount,
+  AcpRuntime,
+  AcpSpawnSpec,
+} from './acp-types.js'
+
+describe('AcpAgentSpec — preset vs command', () => {
+  it('accepts the preset form', () => {
+    const a: AcpAgentSpec = { preset: 'claude' }
+    expectTypeOf(a).toMatchTypeOf<AcpAgentSpec>()
+  })
+
+  it('accepts the explicit form', () => {
+    const a: AcpAgentSpec = { command: 'opencode', args: ['acp'] }
+    expectTypeOf(a).toMatchTypeOf<AcpAgentSpec>()
+  })
+
+  it('forbids both at compile time', () => {
+    // @ts-expect-error — XOR
+    const _: AcpAgentSpec = { preset: 'claude', command: 'overridden' }
+    void _
+  })
+})
+
+describe('AcpRuntime returns a ChildProcess', () => {
+  it('typechecks', () => {
+    const _impl = (rt: AcpRuntime) => {
+      const child: ChildProcess = rt.spawn({ command: 'x', args: [] })
+      return child
+    }
+    void _impl
+  })
+})
+
+describe('AcpSpawnSpec / AcpMount shape', () => {
+  it('mount has path/target/mode', () => {
+    const m: AcpMount = { path: '/host', target: '/container', mode: 'ro' }
+    expectTypeOf(m).toMatchTypeOf<AcpMount>()
+  })
+
+  it('spawn spec carries command, args, optional env/cwd/image/mounts', () => {
+    const s: AcpSpawnSpec = {
+      command: 'foo',
+      args: ['bar'],
+      env: { K: 'v' },
+      cwd: '/x',
+      image: 'img',
+      mounts: [{ path: '/h', target: '/c', mode: 'rw' }],
+    }
+    expectTypeOf(s).toMatchTypeOf<AcpSpawnSpec>()
+  })
+})

package/src/acp-types.ts

@@ -0,0 +1,48 @@
+import type { ChildProcess } from 'node:child_process'
+
+/**
+ * Per-agent ACP block in zooid.yaml. XOR: either a known preset or an
+ * explicit command. The schema parser rejects both/neither.
+ *
+ * Built-in presets: `claude`, `codex`, `opencode`, `cline`, `kiro`, `gemini`.
+ * See `@zooid/acp-client`'s preset registry for the current list.
+ */
+export type AcpAgentSpec =
+  | { preset: string; model?: string; command?: never; args?: never }
+  | { preset?: never; model?: never; command: string; args?: string[] }
+
+/**
+ * A single bind mount the runtime should set up for the spawned agent
+ * process. Only DockerAcpRuntime honors mounts; LocalAcpRuntime ignores them.
+ */
+export interface AcpMount {
+  /** Host-side source path (absolute). */
+  path: string
+  /** Container-side target path. */
+  target: string
+  mode: 'ro' | 'rw'
+}
+
+/**
+ * What an `AcpRuntime` needs in order to launch the ACP agent process.
+ * Unlike the legacy `SpawnConfig`, this is just process-spawn shape — no
+ * adapter-specific concepts (no workspaceReadOnly, no sessionStateDir).
+ */
+export interface AcpSpawnSpec {
+  command: string
+  args: string[]
+  env?: Record<string, string>
+  cwd?: string
+  /** Container image. Used by DockerAcpRuntime; ignored by LocalAcpRuntime. */
+  image?: string
+  /** Bind mounts. Used by DockerAcpRuntime; ignored by LocalAcpRuntime. */
+  mounts?: AcpMount[]
+}
+
+/**
+ * A runtime knows how to spawn the ACP shim process (locally, or inside a
+ * container). Returns a ChildProcess whose stdio is wired up for ACP NDJSON.
+ */
+export interface AcpRuntime {
+  spawn(spec: AcpSpawnSpec): ChildProcess
+}

package/src/approval-correlator.test.ts

@@ -0,0 +1,129 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { ApprovalCorrelator } from './approval-correlator.js'
+import type { ApprovalRequest } from '@zooid/acp-client'
+
+const req = (id: string): ApprovalRequest => ({
+  sessionId: 's-1',
+  toolCallId: id,
+  options: [
+    { optionId: 'allow-once', name: 'Allow once', kind: 'allow_once' },
+    { optionId: 'reject-once', name: 'Reject once', kind: 'reject_once' },
+  ],
+})
+
+describe('ApprovalCorrelator', () => {
+  it('mints a unique approval_id per request', () => {
+    const c = new ApprovalCorrelator()
+    const a = c.register('agent', 's-1', req('tc-1'))
+    const b = c.register('agent', 's-1', req('tc-2'))
+    expect(a.approvalId).not.toBe(b.approvalId)
+  })
+
+  it('resolve() with a matching id resolves the request promise', async () => {
+    const c = new ApprovalCorrelator()
+    const handle = c.register('agent', 's-1', req('tc-1'))
+    queueMicrotask(() =>
+      c.resolve('s-1', handle.approvalId, { decision: 'allow', optionId: 'allow-once' }),
+    )
+    await expect(handle.decisionPromise).resolves.toEqual({
+      decision: 'allow',
+      optionId: 'allow-once',
+    })
+  })
+
+  it('resolve() returns false for an unknown approval id', () => {
+    const c = new ApprovalCorrelator()
+    expect(c.resolve('s-x', 'made-up', { decision: 'cancel' })).toBe(false)
+  })
+
+  it('resolve() returns false when the session id does not match the approval', () => {
+    const c = new ApprovalCorrelator()
+    const handle = c.register('agent', 's-1', req('tc-1'))
+    expect(c.resolve('s-other', handle.approvalId, { decision: 'cancel' })).toBe(false)
+  })
+
+  it('cancelSession() rejects all pending approvals for that session', async () => {
+    const c = new ApprovalCorrelator()
+    const a = c.register('agent', 's-1', req('tc-1'))
+    const b = c.register('agent', 's-1', req('tc-2'))
+    const c3 = c.register('agent', 's-2', req('tc-3'))
+
+    c.cancelSession('s-1')
+    await expect(a.decisionPromise).resolves.toEqual({ decision: 'cancel' })
+    await expect(b.decisionPromise).resolves.toEqual({ decision: 'cancel' })
+    expect(c.size()).toBe(1)
+    // s-2 still pending
+    const settled = await Promise.race([
+      c3.decisionPromise,
+      Promise.resolve('still-pending' as const),
+    ])
+    expect(settled).toBe('still-pending')
+  })
+
+  it('listPending() returns approval requests for a session for SSE replay on reconnect', () => {
+    const c = new ApprovalCorrelator()
+    const h = c.register('agent', 's-1', req('tc-1'))
+    const list = c.listPending('s-1')
+    expect(list).toHaveLength(1)
+    expect(list[0]).toMatchObject({
+      approvalId: h.approvalId,
+      sessionId: 's-1',
+      toolCallId: 'tc-1',
+    })
+  })
+
+  describe('idle timeout', () => {
+    beforeEach(() => vi.useFakeTimers())
+    afterEach(() => vi.useRealTimers())
+
+    it('resolves with cancel after the configured wall-clock timeout', async () => {
+      const c = new ApprovalCorrelator()
+      const handle = c.register('agent', 's-1', req('tc-1'), { timeoutMs: 60_000 })
+      vi.advanceTimersByTime(60_001)
+      await expect(handle.decisionPromise).resolves.toEqual({ decision: 'cancel' })
+    })
+
+    it('emits a timeout signal so the transport can notify the client', async () => {
+      const c = new ApprovalCorrelator()
+      const onTimeout = vi.fn()
+      c.on('timeout', onTimeout)
+      const handle = c.register('agent', 's-1', req('tc-1'), { timeoutMs: 1000 })
+      vi.advanceTimersByTime(1001)
+      await handle.decisionPromise
+      expect(onTimeout).toHaveBeenCalledWith(
+        expect.objectContaining({ approvalId: handle.approvalId, sessionId: 's-1' }),
+      )
+    })
+
+    it('resolve() before the timeout cancels the timer', async () => {
+      const c = new ApprovalCorrelator()
+      const handle = c.register('agent', 's-1', req('tc-1'), { timeoutMs: 60_000 })
+      c.resolve('s-1', handle.approvalId, { decision: 'allow', optionId: 'allow-once' })
+      vi.advanceTimersByTime(60_001)
+      await expect(handle.decisionPromise).resolves.toEqual({
+        decision: 'allow',
+        optionId: 'allow-once',
+      })
+    })
+
+    it('cancelSession() before the timeout cancels the timer', async () => {
+      const c = new ApprovalCorrelator()
+      const handle = c.register('agent', 's-1', req('tc-1'), { timeoutMs: 60_000 })
+      c.cancelSession('s-1')
+      vi.advanceTimersByTime(60_001)
+      await expect(handle.decisionPromise).resolves.toEqual({ decision: 'cancel' })
+      expect(c.size()).toBe(0)
+    })
+
+    it('timeoutMs: 0 disables the timeout (waits forever)', async () => {
+      const c = new ApprovalCorrelator()
+      const handle = c.register('agent', 's-1', req('tc-1'), { timeoutMs: 0 })
+      vi.advanceTimersByTime(60 * 60 * 1000)
+      const settled = await Promise.race([
+        handle.decisionPromise,
+        Promise.resolve('still-pending' as const),
+      ])
+      expect(settled).toBe('still-pending')
+    })
+  })
+})