Merge remote-tracking branch 'origin/master' into codex/pr335-merge-master-20260719

# Conflicts: # packages/support/acp-snapshot/README.md # packages/support/acp-snapshot/src/harness.ts # packages/support/acp-snapshot/src/suite.ts # packages/support/acp-snapshot/tests/harness.spec.ts # packages/support/acp-snapshot/tests/suite.spec.ts
2026-07-19 11:41:10 +08:00
parent 64f64724e5 383a305bd4
commit 39c1c3df4f
330 changed files with 7947 additions and 4450 deletions
--- a/packages/ui/acp/tests/approval.spec.ts
+++ b/packages/ui/acp/tests/approval.spec.ts
@@ -4,9 +4,11 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk'
 import { CallId } from '@deepseek-ai/dsh-llm'
-import { AgentId, type Agent } from '@deepseek-ai/dsh-agent'
+import { type Agent } from '@deepseek-ai/dsh-agent'
+
 import ApprovalService, { type ApprovalRequest } from '@deepseek-ai/dsh-user-approval'
 import { makeBridgeHarness, type BridgeHarness } from './harness.ts'
+import { SessionId } from '@deepseek-ai/dsh-session'

 /**
 * The bridge's `approval/request` answerer: an ask for an agent the bridge
@@ -31,7 +33,7 @@ describe('acp bridge — approval answerer', () => {
  ): Promise<{ agent: Agent; request: ApprovalRequest }> {
    await h.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const { sessionId } = await h.client.newSession({ cwd: process.cwd(), mcpServers: [] })
-    const agent = h.ctx.agents.get(AgentId(sessionId))
+    const agent = h.ctx.agents.get(SessionId(sessionId))
    if (agent === undefined) throw new Error('newSession created no agent')
    // In production an ask always fires mid-turn (tool execution); open one so
    // request()'s turn-enclosure precondition holds for the direct drive below.
@@ -88,9 +90,12 @@ describe('acp bridge — approval answerer', () => {
    await harness.ctx.plugin(ApprovalService)
    harness.onPermission = () => ({ outcome: { outcome: 'selected', optionId: 'allow-once' } })

-    // Not created through the bridge: no bySession entry, so the answerer must
-    // call next() — nobody else answers, so the seam fails closed.
-    const foreign = { session: { events: [{ type: 'turn/start' }], append: () => ({}) } } as unknown as Agent
+    const { agent } = await ownedAgentRequest(harness)
+    // Even an impostor that claims the bridge-owned session id must delegate:
+    // ownership requires the exact Agent object stored in the session record.
+    const foreign = {
+      session: { id: agent.session.id, events: [{ type: 'turn/start' }], append: () => ({}) },
+    } as unknown as Agent
    await expect(harness.ctx.approval.request({ agent: foreign, toolName: 'echo', callId: CallId('c') }))
      .resolves.toBe('unavailable')
    expect(harness.permissionRequests).toHaveLength(0)
--- a/packages/ui/acp/tests/bridge.spec.ts
+++ b/packages/ui/acp/tests/bridge.spec.ts
@@ -3,8 +3,8 @@ import { mkdtemp, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk'
-import { AgentId } from '@deepseek-ai/dsh-agent'
 import { makeBridgeHarness, textResponse, toolCallResponse, type BridgeHarness } from './harness.ts'
+import { SessionId } from '@deepseek-ai/dsh-session'

 /**
 * End-to-end bridge specs over an in-memory transport: a real
@@ -98,7 +98,7 @@ describe('acp bridge', () => {
        required: [],
      },
    })
-    const toolResult = harness.ctx.agents.get(AgentId(sessionId))!.session.events.find(event => event.type === 'tool/result')
+    const toolResult = harness.ctx.agents.get(SessionId(sessionId))!.session.events.find(event => event.type === 'tool/result')
    const toolResultBlock = toolResult?.type === 'tool/result' ? toolResult.data.content[0] : undefined
    const toolResultText = toolResultBlock?.type === 'text' ? toolResultBlock.text : undefined
    expect(toolResultText).toBe('{"answers":[{"id":"language","selected":["Python"]}]}')
@@ -127,7 +127,7 @@ describe('acp bridge', () => {
        required: ['custom'],
      },
    })
-    const toolResult = harness.ctx.agents.get(AgentId(sessionId))!.session.events.find(event => event.type === 'tool/result')
+    const toolResult = harness.ctx.agents.get(SessionId(sessionId))!.session.events.find(event => event.type === 'tool/result')
    expect(JSON.stringify(toolResult)).toContain('apollo')
  })

@@ -136,7 +136,7 @@ describe('acp bridge', () => {
    harness.onElicitation = () => ({ action: 'accept', content: { custom: 'Use Zig' } })
    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
-    const agent = harness.ctx.agents.get(AgentId(sessionId))!
+    const agent = harness.ctx.agents.get(SessionId(sessionId))!

    const result = await harness.ctx.userInteraction.ask({
      agent,
@@ -167,7 +167,7 @@ describe('acp bridge', () => {
    harness.onElicitation = () => ({ action: 'accept', content: { choice: 'TypeScript', custom: 'Use Zig' } })
    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
-    const agent = harness.ctx.agents.get(AgentId(sessionId))!
+    const agent = harness.ctx.agents.get(SessionId(sessionId))!

    await expect(harness.ctx.userInteraction.ask({
      agent,
@@ -184,7 +184,7 @@ describe('acp bridge', () => {
    harness.onElicitation = () => ({ action: 'accept', content: { choice: ['Tests', 'Docs'] } })
    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
-    const agent = harness.ctx.agents.get(AgentId(sessionId))!
+    const agent = harness.ctx.agents.get(SessionId(sessionId))!

    await expect(harness.ctx.userInteraction.ask({
      agent,
@@ -201,11 +201,12 @@ describe('acp bridge', () => {
    harness = await makeBridgeHarness({ storageDir, withAskUser: true })
    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
-    const agent = harness.ctx.agents.get(AgentId(sessionId))!
+    const agent = harness.ctx.agents.get(SessionId(sessionId))!

    await expect(harness.ctx.userInteraction.ask({ questions: [{ id: 'x', question: 'No agent?' }] }))
      .rejects.toMatchObject({ name: 'UserInteractionError', code: 'NO_AGENT' })
-    await expect(harness.ctx.userInteraction.ask({ agent: { id: 'other' } as typeof agent, questions: [{ id: 'x', question: 'No session?' }] }))
+    const impostor = { session: { id: agent.session.id } } as typeof agent
+    await expect(harness.ctx.userInteraction.ask({ agent: impostor, questions: [{ id: 'x', question: 'No session?' }] }))
      .rejects.toMatchObject({ code: 'NO_SESSION' })

    harness.onElicitation = () => ({ action: 'cancel' })
@@ -225,7 +226,7 @@ describe('acp bridge', () => {
    harness = await makeBridgeHarness({ storageDir, withAskUser: true })
    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
-    const agent = harness.ctx.agents.get(AgentId(sessionId))!
+    const agent = harness.ctx.agents.get(SessionId(sessionId))!

    const alreadyAborted = new AbortController()
    alreadyAborted.abort()
@@ -265,8 +266,8 @@ describe('acp bridge', () => {
    expect(b.sessionId).toBeTruthy()
    expect(a.sessionId).not.toBe(b.sessionId)
    // Both agents are live and independently registered.
-    expect(harness.ctx.agents.get(AgentId(a.sessionId))).toBeDefined()
-    expect(harness.ctx.agents.get(AgentId(b.sessionId))).toBeDefined()
+    expect(harness.ctx.agents.get(SessionId(a.sessionId))).toBeDefined()
+    expect(harness.ctx.agents.get(SessionId(b.sessionId))).toBeDefined()
  })

  it('rejects a non-absolute cwd but accepts any absolute cwd (per-session workspace)', async () => {
@@ -281,7 +282,7 @@ describe('acp bridge', () => {
    const res = await harness.client.newSession({ cwd: '/tmp', mcpServers: [] })
    expect(res.sessionId).toBeTruthy()
    // The session header records that cwd, so its bash tools run there.
-    expect(harness.ctx.agents.get(AgentId(res.sessionId))!.session.header.cwd).toBe('/tmp')
+    expect(harness.ctx.agents.get(SessionId(res.sessionId))!.session.header.cwd).toBe('/tmp')
  })

  it('rejects non-empty additionalDirectories', async () => {
@@ -321,7 +322,7 @@ describe('acp bridge', () => {
      ],
    })
    expect(result.stopReason).toBe('end_turn')
-    const user = harness.ctx.agents.get(AgentId(sessionId))!.session.events.find(event => event.type === 'user/message')
+    const user = harness.ctx.agents.get(SessionId(sessionId))!.session.events.find(event => event.type === 'user/message')
    expect(JSON.stringify(user)).toContain('resource_link')
  })

--- a/packages/ui/acp/tests/config-options.spec.ts
+++ b/packages/ui/acp/tests/config-options.spec.ts
@@ -29,7 +29,7 @@ function permissionOption(currentValue: string): object {
  return {
    id: 'permission',
    name: 'Permissions',
-    description: 'Sets this session\'s sandbox and approval behavior.',
+    description: 'The session permission preset: each choice bundles a sandbox mode and an approval policy.',
    category: 'mode',
    type: 'select',
    currentValue,
--- a/packages/ui/acp/tests/dispose.spec.ts
+++ b/packages/ui/acp/tests/dispose.spec.ts
@@ -4,7 +4,6 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk'
 import { SessionId } from '@deepseek-ai/dsh-session'
-import { AgentId } from '@deepseek-ai/dsh-agent'
 import { makeBridgeHarness, textResponse } from './harness.ts'

 describe('acp bridge — disposal & HMR safety', () => {
@@ -17,25 +16,29 @@ describe('acp bridge — disposal & HMR safety', () => {
    const harness = await makeBridgeHarness({ storageDir, script: ['hang'] })
    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
-    const agent = harness.ctx.agents.get(AgentId(sessionId))!
+    const agent = harness.ctx.agents.get(SessionId(sessionId))!

    // Start a prompt that hangs in the model stream.
    const promptDone = harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] })
    await new Promise(r => setTimeout(r, 30))
    expect(agent.status).toBe('running')

-    // Teardown must abort and await the loop: once it resolves the agent is settled, and the
-    // hanging prompt itself completes as cancelled rather than remaining pending.
+    // Dispose the whole context. The bridge's teardown must abort the agent and
+    // AWAIT whenIdle() — so right after dispose resolves, the agent is settled
+    // (not still running). Proves disposal waited, not just requested.
    await harness.ctx.fiber.dispose()
    expect(agent.status).not.toBe('running')

+    // The in-flight prompt settled (cancelled) rather than hanging forever.
    const res = await promptDone
    expect(res.stopReason).toBe('cancelled')
  })

  it('after an ACP-only HMR dispose, a late session/new creates no orphan agent (closed guard)', async () => {
-    // Unload only the bridge while transport and shared services remain live. Its closed guard must
-    // reject late creation before an orphan agent can enter the registry.
+    // Dispose JUST the bridge's fiber (an HMR reload) while agents/agent-loop
+    // stay up and the transport is still live. A late session/new must hit the
+    // `closed` guard and reject — NOT create an agent the disposed bridge can no
+    // longer stream or settle. Verify the world: no agent appeared.
    const harness = await makeBridgeHarness({ storageDir, script: [] })
    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const before = harness.ctx.agents.list().length
@@ -47,21 +50,29 @@ describe('acp bridge — disposal & HMR safety', () => {
  })

  it('an agent created through the bridge is unregistered when ONLY the bridge fiber is disposed', async () => {
-    // The traced service proxy binds loop registration to the caller (bridge) fiber. ACP-only
-    // disposal must therefore reclaim the agent even while agent-loop itself remains mounted.
+    // The factory (`ctx.agents.create`) is reached through the bridge's
+    // traceable service proxy, so `AgentLoop.start`'s `this.ctx.effect(...)`
+    // registration binds to the CALLER context — the bridge fiber — not the
+    // AgentLoop fiber. Disposing JUST the bridge fiber (an ACP-only HMR reload)
+    // must therefore reclaim the agent's registry entry, even though agents/
+    // agent-loop stay up. This pins the fiber-ownership the bridge's teardown
+    // doc comment relies on; if a refactor rebinds the registration to the
+    // AgentLoop fiber, the agent would survive bridge dispose and this fails.
    const harness = await makeBridgeHarness({ storageDir, script: [] })
    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
-    expect(harness.ctx.agents.get(AgentId(sessionId))).toBeDefined()
+    expect(harness.ctx.agents.get(SessionId(sessionId))).toBeDefined()

    await harness.acpFiber.dispose() // tear down ONLY the bridge
-    expect(harness.ctx.agents.get(AgentId(sessionId))).toBeUndefined()
+    expect(harness.ctx.agents.get(SessionId(sessionId))).toBeUndefined()
    await harness.dispose()
  })

  it('no agent is created by a session/new after the bridge has closed (closed guard)', async () => {
-    // Disconnect sets the closed guard and severs the RPC, so registry state—not the rejection
-    // shape—proves a late request did not create an undriveable agent.
+    // After teardown (here a client disconnect sets `closed`), a late
+    // `session/new` must NOT create an orphan agent the bridge can no longer
+    // drive/settle. The transport is gone so the RPC rejects; assert the world:
+    // no new agent appeared in the registry.
    const harness = await makeBridgeHarness({ storageDir, script: [] })
    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const before = harness.ctx.agents.list().length
@@ -73,43 +84,59 @@ describe('acp bridge — disposal & HMR safety', () => {
  })

  it('a client disconnect mid-prompt disposes the session (no registered agent left)', async () => {
-    // Disconnect mid-stream must dispose, not merely idle, the owned agent; otherwise updates would
-    // be swallowed while a registered session survived without a client.
+    // The ACP transport closes (editor quits) while a turn runs. The bridge must
+    // settle the in-flight prompt cancelled and DISPOSE the agent (the session's
+    // per-agent AgentHandle teardown) rather than leaving an orphaned running —
+    // or even idled-but-still-registered — agent whose updates are swallowed.
    const harness = await makeBridgeHarness({ storageDir, script: ['hang'] })
    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
-    const agent = harness.ctx.agents.get(AgentId(sessionId))!
-    // The transport will close before this hanging RPC settles.
+    const agent = harness.ctx.agents.get(SessionId(sessionId))!
+    // Start a prompt that hangs in the model stream. The prompt RPC will never
+    // return (its transport is severed), so do not await it.
    void harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] }).catch(() => {})
    await new Promise(r => setTimeout(r, 30))
    expect(agent.status).toBe('running')

+    // Sever the transport — the bridge's conn.closed teardown runs and drives the
+    // agent's AgentHandle dispose to quiescence on its OWN (before any dispose()).
    await harness.closeClientTransport()
    await agent.whenIdle()
+    // The agent's loop has stopped: status `disposed`.
    expect(agent.status).toBe('disposed')

-    // Await the same memoized bridge teardown without removing root services. It must finish the
-    // AgentHandle teardown and remove both registry records, not just stop the loop.
+    // Await the bridge teardown to completion WITHOUT tearing down the root
+    // agents/sessions services (so we can still query them). acpFiber.dispose()
+    // invokes the SAME memoized quiesce() the disconnect started and awaits its
+    // promise — which resolves only after every rec.dispose() (loop exit +
+    // session removal) has finished, closing the whenIdle()/owned.dispose()
+    // microtask race. The AgentHandle dispose has run: the agent is unregistered
+    // and its session removed from the store, not merely idled (the old
+    // behavior). The services live on the root ctx, so they survive this.
    await harness.acpFiber.dispose()
-    expect(harness.ctx.agents.get(AgentId(sessionId))).toBeUndefined()
+    expect(harness.ctx.agents.get(SessionId(sessionId))).toBeUndefined()
    expect(harness.ctx.sessions.get(SessionId(sessionId))).toBeUndefined()
    await harness.dispose()
  })

  it('a client disconnect racing fiber dispose both reach quiescence (shared teardown)', async () => {
-    // Transport close and fiber disposal can race. Both must await one memoized teardown; a guard
-    // based only on record removal could let the second caller return while the first still drains.
+    // conn.closed teardown and ctx.fiber.dispose() can fire near-simultaneously.
+    // They must share one teardown promise: dispose() must NOT return before the
+    // disconnect teardown's whenIdle() has settled (a `record === undefined`-only
+    // guard would let the second caller return early mid-teardown).
    const harness = await makeBridgeHarness({ storageDir, script: ['hang'] })
    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
-    const agent = harness.ctx.agents.get(AgentId(sessionId))!
+    const agent = harness.ctx.agents.get(SessionId(sessionId))!
    void harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] }).catch(() => {})
    await new Promise(r => setTimeout(r, 30))
    expect(agent.status).toBe('running')

+    // Fire both teardown paths without awaiting the first, then await both.
    const close = harness.closeClientTransport()
    const dispose = harness.ctx.fiber.dispose()
    await Promise.all([close, dispose])
+    // After BOTH settle, the agent has fully drained (not still running).
    expect(agent.status).not.toBe('running')
  })

@@ -117,7 +144,7 @@ describe('acp bridge — disposal & HMR safety', () => {
    const harness = await makeBridgeHarness({ storageDir, script: [] })
    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
-    const session = harness.ctx.agents.get(AgentId(sessionId))!.session
+    const session = harness.ctx.agents.get(SessionId(sessionId))!.session

    await harness.ctx.fiber.dispose()
    const before = harness.updates.length
@@ -129,18 +156,27 @@ describe('acp bridge — disposal & HMR safety', () => {
  })

  it('the final turn closing events are persisted across an AgentHandle dispose (durability)', async () => {
-    // AgentHandle teardown stops and awaits the loop, flushes through still-attached store hooks,
-    // then detaches the session. Reloading verifies that order from durable state.
+    // The teardown-ORDER guarantee: a per-agent dispose must stop the loop,
+    // AWAIT its exit (so the loop's final `turn/end` + `session/flush` fire
+    // through the still-attached store observer → `session/event`), and only
+    // THEN remove its publication hooks and session entry. If the order were inverted
+    // (detach first), the closing events would never reach persistence. Drive a
+    // CLEAN turn to completion, dispose JUST the bridge, then re-load the
+    // persisted log from disk and assert the closing turn/end is on disk — the
+    // world, not the agent's self-report.
    const harness = await makeBridgeHarness({ storageDir, script: [textResponse('done')] })
    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
    await harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] })
-    const liveEvents = harness.ctx.agents.get(AgentId(sessionId))!.session.events.length
+    const liveEvents = harness.ctx.agents.get(SessionId(sessionId))!.session.events.length
    expect(liveEvents).toBeGreaterThan(0)

+    // Tear down JUST the bridge (the AgentHandle dispose runs to quiescence).
    await harness.acpFiber.dispose()
-    expect(harness.ctx.agents.get(AgentId(sessionId))).toBeUndefined()
+    expect(harness.ctx.agents.get(SessionId(sessionId))).toBeUndefined()

+    // Re-load the session from disk: every live event (incl. the closing
+    // turn/end) was flushed before the session was detached.
    const reloaded = await harness.ctx.sessionPersistence.load(SessionId(sessionId))
    expect(reloaded.events.length).toBe(liveEvents)
    const last = reloaded.events.at(-1)!
@@ -149,20 +185,35 @@ describe('acp bridge — disposal & HMR safety', () => {
  })

  it('a turn aborted BY the dispose still flushes its closing turn/end to disk (durability, mid-turn)', async () => {
-    // Here disposal itself makes the loop append `turn/end {disposed}` and flush. Reload must find
-    // that real closer, not crash recovery's synthetic `interrupted`, proving detach ran last.
+    // The teardown-order contract only earns its keep when the closing events are
+    // produced BY the dispose itself. Here the model stream HANGS, so the turn is
+    // still open when teardown runs: the composite agent effect stops the loop,
+    // the loop unwinds and appends `turn/end {disposed}` + runs its final
+    // `session/flush` — all while the store-owned publication hooks are still attached (the session
+    // detach is the LAST disposer in the same effect's LIFO chain) — and only
+    // THEN is the session detached. If the order were inverted (or the session
+    // were a racing SIBLING effect), the abort-produced `turn/end` would never
+    // reach disk and a re-load would instead show crash-recovery's synthetic
+    // `interrupted` closer. Re-load from disk and assert the REAL `disposed`
+    // reason landed — proving the loop's own closing event was captured, not a
+    // recovered substitute.
    const harness = await makeBridgeHarness({ storageDir, script: ['hang'] })
    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
-    const agent = harness.ctx.agents.get(AgentId(sessionId))!
+    const agent = harness.ctx.agents.get(SessionId(sessionId))!
    void harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] }).catch(() => {})
    await new Promise(r => setTimeout(r, 30))
    expect(agent.status).toBe('running')
+    // The turn is OPEN in the log (turn/start appended, no turn/end yet).
    const openTurnEnds = agent.session.events.filter(e => e.type === 'turn/end').length

+    // Dispose JUST the bridge: a fiber unload that must STILL honor the ordered
+    // teardown (the composite effect runs its disposer chain as a unit).
    await harness.acpFiber.dispose()
-    expect(harness.ctx.agents.get(AgentId(sessionId))).toBeUndefined()
+    expect(harness.ctx.agents.get(SessionId(sessionId))).toBeUndefined()

+    // The loop's own `turn/end {disposed}` is on disk (re-load: the world, not
+    // self-report) — NOT a crash-recovery `interrupted` substitute.
    const reloaded = await harness.ctx.sessionPersistence.load(SessionId(sessionId))
    const persistedTurnEnds = reloaded.events.filter(e => e.type === 'turn/end')
    expect(persistedTurnEnds.length).toBe(openTurnEnds + 1)
@@ -171,55 +222,71 @@ describe('acp bridge — disposal & HMR safety', () => {
  })

  it('per-session AgentHandle dispose leaves sibling agents untouched', async () => {
-    // A per-session handle owns exactly one agent and session. Dispose A and assert B remains fully
-    // published, which guards against context-wide teardown.
+    // The factory returns a per-agent AgentHandle whose dispose() tears down
+    // EXACTLY that agent + its session — RFC 011 isolation. Create two agents
+    // directly through the registry factory (the same path the ACP bridge uses),
+    // dispose one handle, and assert the other survives, registered and
+    // queryable, with its session still in the store.
    const harness = await makeBridgeHarness({ storageDir, script: [] })
    const handleA = await harness.ctx.agents.create({
-      agentId: AgentId('sib-a'), sessionId: SessionId('sib-a'), agentOptions: { provider: 'mock', model: 'mock' },
+      sessionId: SessionId('sib-a'), agentOptions: { provider: 'mock', model: 'mock' },
    })
    const handleB = await harness.ctx.agents.create({
-      agentId: AgentId('sib-b'), sessionId: SessionId('sib-b'), agentOptions: { provider: 'mock', model: 'mock' },
+      sessionId: SessionId('sib-b'), agentOptions: { provider: 'mock', model: 'mock' },
    })
-    expect(harness.ctx.agents.get(AgentId('sib-a'))).toBe(handleA.agent)
-    expect(harness.ctx.agents.get(AgentId('sib-b'))).toBe(handleB.agent)
+    expect(harness.ctx.agents.get(SessionId('sib-a'))).toBe(handleA.agent)
+    expect(harness.ctx.agents.get(SessionId('sib-b'))).toBe(handleB.agent)

    await handleA.dispose()
-    expect(harness.ctx.agents.get(AgentId('sib-a'))).toBeUndefined()
+    // A is gone — unregistered AND its session removed from the store.
+    expect(harness.ctx.agents.get(SessionId('sib-a'))).toBeUndefined()
    expect(harness.ctx.sessions.get(SessionId('sib-a'))).toBeUndefined()
    expect(handleA.agent.status).toBe('disposed')
-    expect(harness.ctx.agents.get(AgentId('sib-b'))).toBe(handleB.agent)
+    // B is wholly unaffected.
+    expect(harness.ctx.agents.get(SessionId('sib-b'))).toBe(handleB.agent)
    expect(harness.ctx.sessions.get(SessionId('sib-b'))).toBeDefined()
    expect(handleB.agent.status).not.toBe('disposed')
    await harness.dispose()
  })

  it('a throwing agent/disposed listener does not prevent session removal (composite-effect containment)', async () => {
-    // Composite disposers run in sequence. A throwing `agent/disposed` listener must be contained or
-    // it would skip later session detach, leaking publication hooks and creating a durability hole.
+    // The AgentHandle teardown folds session-detach, register, and loop-stop
+    // into ONE composite effect whose disposers run as a `.then()` chain. The
+    // register disposer emits `agent/disposed`; if a listener throws and the
+    // emit is UNCONTAINED, the rejected chain skips the LATER session-detach
+    // disposer — stranding the session in the store with its publication hooks attached (a
+    // leak AND a durability hole, since the new design relies on detach
+    // running). The emit must be contained. Register a throwing listener, drive
+    // a clean turn, dispose, and assert the session was STILL removed.
    const harness = await makeBridgeHarness({ storageDir, script: [textResponse('ok')] })
    harness.ctx.on('agent/disposed', () => { throw new Error('boom disposed listener') })
    const handle = await harness.ctx.agents.create({
-      agentId: AgentId('guard-a'), sessionId: SessionId('guard-a'), agentOptions: { provider: 'mock', model: 'mock' },
+      sessionId: SessionId('guard-a'), agentOptions: { provider: 'mock', model: 'mock' },
    })
    handle.agent.send([{ type: 'text', text: 'go' }])
    await handle.agent.whenIdle()
    expect(harness.ctx.sessions.get(SessionId('guard-a'))).toBeDefined()

+    // Dispose: the throwing listener must NOT break the chain before detach.
    await handle.dispose()
-    expect(harness.ctx.agents.get(AgentId('guard-a'))).toBeUndefined()
+    expect(harness.ctx.agents.get(SessionId('guard-a'))).toBeUndefined()
    expect(harness.ctx.sessions.get(SessionId('guard-a'))).toBeUndefined() // detach still ran
    await harness.dispose()
  })

  it('concurrent AgentHandle dispose() calls all await the SAME teardown (memoized)', async () => {
-    // The Cordis effect disposer is single-shot and would let a second call return after its epoch
-    // clears. AgentHandle must memoize the whole async teardown so every caller awaits quiescence.
+    // The handle's dispose() must memoize: the underlying cordis effect disposer
+    // is single-shot, so a second dispose() while the first is mid-teardown would
+    // otherwise resolve IMMEDIATELY (effect epoch already cleared) — before the
+    // first call's await agent.done + final flush finished. Every caller must
+    // observe the same quiescence boundary.
    const harness = await makeBridgeHarness({ storageDir, script: ['hang'] })
    const handle = await harness.ctx.agents.create({
-      agentId: AgentId('conc-a'), sessionId: SessionId('conc-a'), agentOptions: { provider: 'mock', model: 'mock' },
+      sessionId: SessionId('conc-a'), agentOptions: { provider: 'mock', model: 'mock' },
    })
-    // A hanging turn makes disposal produce a final flush; gate it so the second call arrives while
-    // teardown is observably in flight.
+    // Drive a turn that hangs in the model stream, so the loop is mid-turn when
+    // disposed — its exit runs a final session/flush we can gate to hold the
+    // teardown observably in-flight.
    handle.agent.send([{ type: 'text', text: 'go' }])
    await new Promise(r => setTimeout(r, 30))
    expect(handle.agent.status).toBe('running')
@@ -227,21 +294,25 @@ describe('acp bridge — disposal & HMR safety', () => {
    const flushGate = new Promise<void>((resolve) => { releaseFlush = resolve })
    harness.ctx.on('session/flush', () => flushGate)

+    // First dispose enters teardown (aborts the hanging step) and blocks in the
+    // gated final flush.
    const first = handle.dispose()
    let firstSettled = false
    void first.then(() => { firstSettled = true })
    await new Promise(r => setTimeout(r, 20))
    expect(firstSettled).toBe(false)

+    // Second dispose MUST await the same in-flight teardown, not resolve early.
    const second = handle.dispose()
    let secondSettled = false
    void second.then(() => { secondSettled = true })
    await new Promise(r => setTimeout(r, 20))
    expect(secondSettled).toBe(false) // memoized: still pending with the first

+    // Release the flush; both resolve together and the session is gone.
    releaseFlush()
    await Promise.all([first, second])
-    expect(harness.ctx.agents.get(AgentId('conc-a'))).toBeUndefined()
+    expect(harness.ctx.agents.get(SessionId('conc-a'))).toBeUndefined()
    expect(harness.ctx.sessions.get(SessionId('conc-a'))).toBeUndefined()
    await harness.dispose()
  })
--- a/packages/ui/acp/tests/edges.spec.ts
+++ b/packages/ui/acp/tests/edges.spec.ts
@@ -3,7 +3,6 @@ import { mkdtemp, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk'
-import { AgentId } from '@deepseek-ai/dsh-agent'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import { makeBridgeHarness, textResponse, type BridgeHarness } from './harness.ts'

@@ -27,7 +26,7 @@ describe('acp bridge — demux & config edges', () => {
    await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
    const before = harness.updates.length

-    const { agent: foreign } = await harness.ctx.agents.create({ agentId: AgentId('foreign'), sessionId: SessionId('foreign-session'), agentOptions: { provider: 'mock', model: 'mock' } })
+    const { agent: foreign } = await harness.ctx.agents.create({ sessionId: SessionId('foreign-session'), agentOptions: { provider: 'mock', model: 'mock' } })
    foreign.send([{ type: 'text', text: 'hi' }])
    await foreign.whenIdle()
    await new Promise(r => setTimeout(r, 10))
--- a/packages/ui/acp/tests/load.spec.ts
+++ b/packages/ui/acp/tests/load.spec.ts
@@ -4,7 +4,6 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk'
 import { SESSION_FORMAT_VERSION, SessionId } from '@deepseek-ai/dsh-session'
-import { AgentId } from '@deepseek-ai/dsh-agent'
 import { makeBridgeHarness, textResponse, toolCallResponse, type BridgeHarness, type CapturedUpdate } from './harness.ts'

 /** Concatenate the text of all agent_message_chunk updates. */
@@ -185,7 +184,7 @@ describe('acp bridge — session/load replay', () => {
    release()                            // resume() finishes AFTER teardown
    expect(await loadResult).toBe('rejected')
    // No live agent was installed for the closed connection.
-    expect(loader.ctx.agents.get(AgentId(sessionId))).toBeUndefined()
+    expect(loader.ctx.agents.get(SessionId(sessionId))).toBeUndefined()
  })

  it('rejects load when the requested cwd does not match the persisted session cwd', async () => {
@@ -205,11 +204,11 @@ describe('acp bridge — session/load replay', () => {
    await loader.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    await expect(loader.client.loadSession({ sessionId: 'elsewhere', cwd: process.cwd(), mcpServers: [] }))
      .rejects.toThrow(/cwd mismatch/)
-    expect(loader.ctx.agents.get(AgentId('elsewhere'))).toBeUndefined()
+    expect(loader.ctx.agents.get(SessionId('elsewhere'))).toBeUndefined()

    const res = await loader.client.loadSession({ sessionId: 'elsewhere', cwd: `${otherCwd}/.`, mcpServers: [] })
    expect(res).toBeDefined()
-    expect(loader.ctx.agents.get(AgentId('elsewhere'))!.session.header.cwd).toBe(otherCwd)
+    expect(loader.ctx.agents.get(SessionId('elsewhere'))!.session.header.cwd).toBe(otherCwd)
  })

  it('rejects load for a non-absolute cwd (still required to be absolute)', async () => {
@@ -243,7 +242,7 @@ describe('acp bridge — session/load replay', () => {
    // Rejected BEFORE resume (metadata-only check) — no agent was registered, so
    // the id is not wedged: a later attempt hits the same clean rejection, not a
    // duplicate-registration error.
-    expect(loader.ctx.agents.get(AgentId('legacy'))).toBeUndefined()
+    expect(loader.ctx.agents.get(SessionId('legacy'))).toBeUndefined()
    await expect(loader.client.loadSession({ sessionId: 'legacy', cwd: process.cwd(), mcpServers: [] }))
      .rejects.toThrow(/no absolute persisted cwd/)
  })
--- a/packages/ui/acp/tests/multi-session.spec.ts
+++ b/packages/ui/acp/tests/multi-session.spec.ts
@@ -3,8 +3,8 @@ import { mkdtemp, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk'
-import { AgentId } from '@deepseek-ai/dsh-agent'
 import { makeBridgeHarness, textResponse, type BridgeHarness, type CapturedUpdate } from './harness.ts'
+import { SessionId } from '@deepseek-ai/dsh-session'

 /** Text of the agent_message_chunk updates scoped to one session id. */
 function messageTextFor(updates: { sessionId?: string; update: CapturedUpdate }[], sessionId: string): string {
@@ -102,8 +102,8 @@ describe('acp bridge — RFC 011 multi-session isolation', () => {
    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const a = (await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })).sessionId
    const b = (await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })).sessionId
-    const agentA = harness.ctx.agents.get(AgentId(a))!
-    const agentB = harness.ctx.agents.get(AgentId(b))!
+    const agentA = harness.ctx.agents.get(SessionId(a))!
+    const agentB = harness.ctx.agents.get(SessionId(b))!

    // Wait deterministically for BOTH agents to enter `running` (not a fixed
    // sleep — agent startup latency is unbounded on a loaded worker).
--- a/packages/ui/acp/tests/turns.spec.ts
+++ b/packages/ui/acp/tests/turns.spec.ts
@@ -3,7 +3,6 @@ import { mkdtemp, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import { AgentId } from '@deepseek-ai/dsh-agent'
 import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk'
 import {
  errorResponse,
@@ -13,6 +12,7 @@ import {
  toolCallResponse,
  type BridgeHarness,
 } from './harness.ts'
+import { SessionId } from '@deepseek-ai/dsh-session'

 /** Boilerplate: initialize + create one session, returning its id. */
 async function newSession(h: BridgeHarness, clientCapabilities: Record<string, unknown> = {}): Promise<string> {
@@ -274,7 +274,7 @@ describe('acp bridge — turn outcomes', () => {
    // OWN turn with the real model answer.
    harness = await makeBridgeHarness({ storageDir, script: [textResponse('real answer')] })
    const sessionId = await newSession(harness)
-    const agent = harness.ctx.agents.get(AgentId(sessionId))!
+    const agent = harness.ctx.agents.get(SessionId(sessionId))!
    // On the queued prompt, synchronously inject a one-shot context turn (idle
    // inject writes turn/start{injection} → context/message → turn/end). Fire
    // once so it lands between install and the prompt turn.
@@ -328,7 +328,7 @@ describe('acp bridge — turn outcomes', () => {
    await harness.client.cancel({ sessionId })
    const res = await promptDone
    expect(res.stopReason).toBe('cancelled')
-    const agent = harness.ctx.agents.get(AgentId(sessionId))!
+    const agent = harness.ctx.agents.get(SessionId(sessionId))!
    await agent.whenIdle()
    const turnStarts = agent.session.events.filter(e => e.type === 'turn/start').length
    expect(turnStarts).toBeLessThanOrEqual(1)