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

packages/ui/acp/README.md

@@ -8,7 +8,7 @@ It is a **client-driver / UI plugin**, the structured analogue of the readline `
 
 `apply(ctx, config)` — wires an `AgentSideConnection` (from `@agentclientprotocol/sdk`) to `process.stdin`/`process.stdout` and implements the ACP `Agent` method surface.
 
-The plugin injects `agents`, `sessions`, `sessionPersistence`, `tools`, `userInteraction`, `llm`, and `systemPrompt`, never the concrete loop. Persistence backs `session/load`; the LLM catalog backs model selection; prompt assembly keeps model variables aligned with routing; tool definitions own presentation; user interaction maps agent questions to ACP forms.
+The plugin injects `agents`, `sessionPersistence`, `tools`, `userInteraction`, `llm`, and `systemPrompt`, never the concrete loop. Persistence backs `session/load`; the LLM catalog backs model selection; prompt assembly keeps model variables aligned with routing; tool definitions own presentation; user interaction maps agent questions to ACP forms.
 
 ### Config
 
@@ -37,7 +37,7 @@ The `initialize` handshake reports a fixed server identity (`agentInfo: { name:
 
 ## Multi-session
 
-Forward and reverse indexes route every event, prompt, cancel, and approval to one session. Each session permits one in-flight prompt; teardown drains all sessions in parallel. See the [multi-session RFC](../../../docs/rfc/implemented/feature/2026-06-14-acp-multi-session.md).
+One id-keyed record map plus exact agent-object checks route every event, prompt, cancel, and approval to one session. Each session permits one in-flight prompt; teardown drains all sessions in parallel. See the [multi-session RFC](../../../docs/rfc/implemented/feature/2026-06-14-acp-multi-session.md).
 
 ## Session config options
 

packages/ui/acp/src/index.ts

@@ -1,8 +1,8 @@
 /**
- * Multi-session ACP server bridge over JSON-RPC stdio. Creates or resumes
- * agents, routes their events, settles prompts by turn, and answers approvals.
- * Each session keeps independent presentation and prompt-correlation state so
- * concurrent streams cannot cross. Stdout is reserved for protocol frames.
+ * Multi-session ACP bridge over JSON-RPC stdio. Creates or resumes agents,
+ * routes session-scoped events and approvals, and settles prompts by turn.
+ * Stdout is reserved for protocol frames.
+ *
  * @module @deepseek-ai/dsh-acp
  */
 
@@ -45,7 +45,6 @@ import {
 import type { ContentBlock, LlmCallConfig, LlmModelInfo, LlmProviderInfo } from '@deepseek-ai/dsh-llm'
 import { assertNever, CallId } from '@deepseek-ai/dsh-llm'
 import type { Agent } from '@deepseek-ai/dsh-agent'
-import { AgentId } from '@deepseek-ai/dsh-agent'
 import { SessionId } from '@deepseek-ai/dsh-session'
 // Side-effect type import: resolves `ctx.get('permission')` to the service.
 import type {} from '@deepseek-ai/dsh-permission'
@@ -76,16 +75,15 @@ import {
 } from './codec.ts'
 
 export const name = 'acp'
-// Interface services back advertised loading, tool-owned presentation with a generic fallback, and interaction.
-// TODO(acp-session-inject): remove `sessions`; the bridge never reads it, and ownership is already behind `agents`.
-export const inject = ['agents', 'sessions', 'sessionPersistence', 'tools', 'userInteraction', 'llm', 'systemPrompt']
+// Interface services back loading, presentation, interaction, and prompt assembly.
+export const inject = ['agents', 'sessionPersistence', 'tools', 'userInteraction', 'llm', 'systemPrompt']
 
-/** Build an ACP invalid-params error with visible human detail. */
+/** Preserve invalid-parameter detail in the SDK wire error message. */
 function invalidParams(detail: string): RequestError {
   return RequestError.invalidParams(undefined, detail)
 }
 
-/** Build an ACP internal error with visible detail; plain handler errors are flattened on wire. */
+/** Preserve failed-turn detail; plain handler errors become a generic wire internal error. */
 function internalError(detail: string): RequestError {
   return RequestError.internalError(undefined, detail)
 }
@@ -210,7 +208,7 @@ export interface AcpConfig {
   provider?: string
   /** Model name for created agents (must have a registered adapter). */
   model?: string
-  /** Runtime-only transport override for tests; production uses stdio. */
+  /** Runtime-only transport override; production uses stdio. */
   stream?: Stream
 }
 
@@ -246,13 +244,12 @@ interface ModelCatalogEntry {
 
 /** Per-session bridge state keyed by ACP session id. */
 interface SessionRecord {
-  sessionId: SessionId
   agent: Agent
-  /** Owned-agent disposer that reaches per-session quiescence. */
+  /** Exact owned-agent disposer; resolves after registry, loop, and session teardown. */
   dispose: () => Promise<void>
-  /** Per-session tool presenter and in-flight call correlation. */
+  /** Per-session tool presentation and call/result correlation. */
   presenter: ToolPresenter
-  /** Session-creation snapshot of terminal-card support for call/result consistency. */
+  /** Terminal capability snapshot shared by matching call and result updates. */
   terminalEnabled: boolean
   /** Session-local provider/model selection and the current step snapshot. */
   target: LlmTargetRef
@@ -262,10 +259,7 @@ interface SessionRecord {
     reject: (error: Error) => void
     turn: number | undefined
   } | undefined
-  /**
-   * Idle config changes awaiting a turn-enclosed log anchor; last write wins.
-   * Responses overlay them, but a restart before anchoring restores the logged fold.
-   */
+  /** Last idle switch per knob, anchored before the next prompt assembles. */
   pendingSwitches: { preset?: string }
 }
 
@@ -276,14 +270,15 @@ interface SessionRecord {
  * correlation in a `finally` so presentation failure cannot starve settlement.
  */
 export function apply(ctx: Context, config: AcpConfig): void {
-  // Handlers run later outside this injection scope, so capture services now.
+  // ACP handlers execute outside this plugin's injection scope, so capture
+  // injected services during apply(); lazy service reads in a handler fail.
   const agents = ctx.agents
   const llm = ctx.llm
   const sessionPersistence = ctx.sessionPersistence
   const logger = ctx.logger
   const tools = ctx.tools
   const userInteraction = ctx.userInteraction
-  // Presenter failures are logged and contained per session or replay.
+  // Presenter callbacks are contained so display failures cannot break protocol handling.
   const makePresenter = (agent?: Agent): ToolPresenter => new ToolPresenter(tools, (message) => { logger.warn(message) }, agent)
 
   /** Resolve a complete target only; partial config remains available to other request listeners. */
@@ -381,16 +376,12 @@ export function apply(ctx: Context, config: AcpConfig): void {
     }
   }
 
-  // TODO(derive-acp-session-id): derive event ids from `agent.session`, verify ownership, then remove the reverse map.
-  // Agent events currently carry only the Agent, so retain `SessionRecord.sessionId` and update both indexes together.
-  // Dropping the forward record lets the weak reverse entry expire.
   const sessions = new Map<SessionId, SessionRecord>()
-  const bySession = new WeakMap<Agent, SessionId>()
-  // Reserve ids across asynchronous resume; distinct ids still load concurrently.
+  // Reserve an id before resume so pipelined load/new requests cannot duplicate it.
   const loadingIds = new Set<SessionId>()
-  // Post-await checks prevent a closing bridge from publishing resumed sessions.
+  // Async creation checks this after awaits to avoid publishing after teardown.
   let closed = false
-  // Connection-level capability copied into each new session record.
+  // Each new or loaded session snapshots the latest connection capability.
   let terminalOutputCap = false
 
   // Assigned at the bottom, before any agent event can fire (a session only
@@ -398,20 +389,26 @@ export function apply(ctx: Context, config: AcpConfig): void {
   // `notify` never observes it unset — no undefined guard needed.
   let conn: AgentSideConnection
 
+  /** Return the bridge-owned record for an agent, rejecting same-id impostors. */
+  const ownedRecord = (agent: Agent): SessionRecord | undefined => {
+    const rec = sessions.get(agent.session.id)
+    return rec?.agent === agent ? rec : undefined
+  }
+
   userInteraction.registerProvider({
     async ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer> {
       if (request.agent === undefined) {
         throw new UserInteractionError('ACP user questions must come from an agent-owned request', 'NO_AGENT')
       }
-      const sessionId = bySession.get(request.agent)
-      if (sessionId === undefined) {
+      const rec = ownedRecord(request.agent)
+      if (rec === undefined) {
         throw new UserInteractionError('ACP user question has no matching session', 'NO_SESSION')
       }
       const answers: AskUserQuestionAnswerItem[] = []
       for (const question of request.questions) {
         const options = question.options ?? []
         const response = await withAbort(conn.unstable_createElicitation(
-          elicitationForQuestion(sessionId, question, options),
+          elicitationForQuestion(rec.agent.session.id, question, options),
         ), request.signal).catch((error: unknown) => {
           if (error instanceof UserInteractionError) throw error
           throw new UserInteractionError('ACP elicitation request failed', 'ASK_FAILED', { cause: error })
@@ -506,13 +503,13 @@ export function apply(ctx: Context, config: AcpConfig): void {
   // whose end arrives late is ignored (see
   // SessionRecord.inflight). A turn that ends `error` REJECTS the prompt (ACP
   // has no error stop reason); other reasons resolve via the codec. Demux
-  // strictly by session id: a `session/event` is routed to its own record, so
-  // two sessions streaming at once never cross-settle or interleave updates.
+  // strictly by session id: concurrent updates may alternate on the shared
+  // connection, but they retain the owning id and never cross-settle.
   ctx.on('session/event', (session, event: SessionEvent) => {
     const rec = sessions.get(session.header.id)
     if (rec === undefined) return
     try {
-      streamSessionEventUpdate(rec.sessionId, event, notify, rec.presenter, {
+      streamSessionEventUpdate(rec.agent.session.id, event, notify, rec.presenter, {
         enabled: rec.terminalEnabled,
         cwd: session.header.cwd,
       }, { includeUserMessages: false })
@@ -543,12 +540,12 @@ export function apply(ctx: Context, config: AcpConfig): void {
   // allow_always is a grant-storage design the approval RFC defers, so the
   // prompt never offers a durable grant the harness could not honor.
   ctx.on('approval/request', (req, next) => {
-    const sessionId = bySession.get(req.agent)
+    const rec = ownedRecord(req.agent)
     // The protocol requires `toolCall` (the prompt renders attached to it), so
     // a request without a callId has nothing to attach to — delegate.
-    if (sessionId === undefined || req.callId === undefined) return next()
+    if (rec === undefined || req.callId === undefined) return next()
     return conn.requestPermission({
-      sessionId,
+      sessionId: rec.agent.session.id,
       toolCall: { toolCallId: req.callId },
       options: [
         { optionId: 'allow-once', name: 'Allow once', kind: 'allow_once' },
@@ -577,26 +574,19 @@ export function apply(ctx: Context, config: AcpConfig): void {
     return [...options, {
       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,
       options: [
         ...presets.names.map((name: string) => presets.optionOf(name)),
-        // `custom` is offered only as the current-value echo, never as a target.
+        // `custom` echoes the current derived state but is never a target.
         ...currentValue === 'custom' ? [presets.optionOf('custom')] : [],
       ],
     }]
   }
 
-  /**
-   * Whether the session's log currently has an open turn — the last boundary
-   * event is a `turn/start`. Decides whether a config switch may append NOW
-   * (enclosed) or must wait for the next prompt submission (see
-   * {@link SessionRecord.pendingSwitches}). Read from the LOG, not
-   * `agent.status`: status stays `running` across the gap between two queued
-   * turns, where a bare append would still land outside any turn.
-   */
+  /** Whether the log has an open turn in which a config switch can be enclosed. */
   const isTurnOpen = (agent: Agent): boolean => {
     const events = agent.session.events
     for (let index = events.length - 1; index >= 0; index -= 1) {
@@ -607,29 +597,22 @@ export function apply(ctx: Context, config: AcpConfig): void {
     return false
   }
 
-  /**
-   * Anchor a pending preset in the open turn. `PermissionService.set()` skips
-   * net-zero changes, so the log records switches rather than select clicks.
-   */
+  /** Anchor last-write-wins idle switches into a just-opened turn. */
   const flushPendingSwitches = (rec: SessionRecord): void => {
     const pending = rec.pendingSwitches
     rec.pendingSwitches = {}
     if (pending.preset === undefined) return
     const presets = ctx.get('permission')
     /* v8 ignore next -- a pending preset exists only if the service answered the
-       switch; a valid composition cannot unmount it before anchoring. */
+       switch; it cannot unmount between that and the next turn in any composition. */
     if (presets === undefined) return
     presets.set(rec.agent.session, pending.preset)
   }
 
-  // Anchor idle switches on the next prompt submission: its turn is open, but
-  // request assembly has not begun. This handler runs outside log emission, so
-  // invariants and persistence observe the events in log order; the first flush
-  // clears pending state. Promptless injection turns leave the switch pending,
-  // with no request or execution under stale settings.
+  // Prompt-submit is inside the new turn but before prompt assembly. Promptless
+  // injection turns leave the switch pending because they execute no request.
   ctx.on('agent/prompt-submit', (agent, _content, _source, next) => {
-    const sessionId = bySession.get(agent)
-    const rec = sessionId === undefined ? undefined : sessions.get(sessionId)
+    const rec = ownedRecord(agent)
     if (rec !== undefined) flushPendingSwitches(rec)
     return next()
   })
@@ -677,25 +660,20 @@ export function apply(ctx: Context, config: AcpConfig): void {
         const directory = modelDirectory(await readModelCatalog(), target.current)
         assertOpen()
         const handle = await agents.create({
-          agentId: AgentId(sessionId),
           sessionId,
           meta: { cwd: params.cwd },
           agentOptions: agentOptions(config),
           setup: (agentCtx) => { installTarget(agentCtx, target) },
         })
-        // Creation awaits the unpublished setup transaction. A client disconnect
-        // can therefore close this bridge
-        // after the entry check but before the handle resolves; never install a
-        // post-close record that quiesce() could not have seen.
+        // Agent creation may resolve after the bridge closes; dispose the handle
+        // instead of publishing a record that teardown could not observe.
         /* v8 ignore next 4 -- the in-memory transport rejects the in-flight RPC
            immediately on close; real stdio may let the handler resume */
         if (closed) {
           await handle.dispose()
           throw internalError('connection closed during session/new')
         }
-        bySession.set(handle.agent, sessionId)
         sessions.set(sessionId, {
-          sessionId,
           agent: handle.agent,
           dispose: () => handle.dispose(),
           presenter: makePresenter(handle.agent),
@@ -753,7 +731,6 @@ export function apply(ctx: Context, config: AcpConfig): void {
           assertOpen()
           const target: LlmTargetRef = { current: configuredTarget(), assembled: undefined }
           const handle = await agents.resume({
-            agentId: AgentId(sessionId),
             resumeSessionId: sessionId,
             agentOptions: agentOptions(config),
             setup: (agentCtx) => { installTarget(agentCtx, target) },
@@ -774,13 +751,11 @@ export function apply(ctx: Context, config: AcpConfig): void {
           }
           const directory = modelDirectory(catalog, target.current)
           const agent = handle.agent
-          bySession.set(agent, sessionId)
           // Snapshot the terminal capability ONCE for this session (used by both
           // the replay below and the post-load live stream) so a later
           // `initialize` can't desync the call/result of a tool card.
           const terminalEnabled = terminalOutputCap
           const record: SessionRecord = {
-            sessionId,
             agent,
             dispose: () => handle.dispose(),
             presenter: makePresenter(agent),
@@ -899,8 +874,7 @@ export function apply(ctx: Context, config: AcpConfig): void {
             if (presets === undefined) {
               throw invalidParams(`unknown permission value ${JSON.stringify(params.value)}`)
             }
-            // Clients may re-send the current selection on session start. Accept
-            // that echo without logging; this is the only valid `custom` request.
+            // A current-value echo is acknowledged without recording a switch.
             const current = rec.pendingSwitches.preset ?? presets.current(rec.agent.session.events)
             if (params.value === current) break
             if (!presets.names.includes(params.value)) {
@@ -1083,7 +1057,7 @@ function validateMcpServers(params: { mcpServers?: unknown[] }): void {
  * zero or more times per event (best-effort UI feed, never load-bearing).
  * @param presenter - resolves tool-owned render intent for tool events;
  * defaults to the generic-fallback {@link nullToolPresenter}.
- * @param terminal - the connection's terminal-rendering context; defaults to
+ * @param terminal - the session's terminal-rendering context; defaults to
  * disabled (the plain-text console-block fallback).
  * @param options - `includeUserMessages` (default `true`): live streaming
  * passes `false` so a prompt the client just sent is not echoed back.
@@ -1142,16 +1116,16 @@ export function streamSessionEventUpdate(
 }
 
 /**
- * Map a whole harness todo list to an ACP plan, assigning medium priority.
- * Statuses map directly and ACP replaces its whole plan on each update.
- * @param todos - the harness todo list (the whole list, not a diff).
- * @returns the ACP plan body, one entry per todo.
+ * Map a whole harness todo list to an ACP replacement plan, using medium
+ * priority because harness todos do not carry one.
+ * @param todos - complete harness todo list.
+ * @returns one ACP plan entry per todo.
  */
 export function todosToPlan(todos: TodoItem[]): Plan {
   return { entries: todos.map((todo): PlanEntry => ({ content: todo.content, priority: 'medium', status: todo.status })) }
 }
 
-/** Terminal-card capability and workspace context for event rendering. */
+/** Per-session terminal capability and workspace used while translating updates. */
 export interface TerminalRendering {
   enabled: boolean
   /** The session workspace cwd (terminal-card header default); `undefined` when the session has none. */
@@ -1162,31 +1136,31 @@ export interface TerminalRendering {
 const noTerminalRendering: TerminalRendering = { enabled: false, cwd: undefined }
 
 /**
- * Resolve tool-owned call/result views with generic fallbacks. Per-session
- * call-id state supplies the tool name and arguments omitted from result events.
- * Each entry is consumed by its result; any remainder dies with the session.
+ * Resolve tool-owned call/result views with a generic fallback. Per-session
+ * state correlates results with call arguments; interrupted calls may retain an
+ * entry only until that session's presenter is discarded.
  */
 export class ToolPresenter {
   private readonly pending = new Map<CallId, { name: string; args: unknown; card: ToolCallView['card'] }>()
 
   /**
-   * @param tools the registry to resolve tool definitions by name.
-   * @param onError receives contained presenter failures before generic fallback.
+   * @param tools - registry used to resolve executing definitions.
+   * @param onError - contained presenter-error sink before generic fallback.
+   * @param agent - optional scoped registry view for the executing agent.
    */
   constructor(
     private readonly tools: Pick<ToolRegistry, 'get'>,
     private readonly onError: (message: string) => void = () => {},
-    /** Agent scope for tool lookup; absent during replay without a live agent. */
     private readonly agent?: Agent,
   ) {}
 
   /**
-   * Resolve a pending call and remember its state for the matching result.
+   * Pending-state render intent for a `tool/call`; remembers `(name, args, card)`
+   * for the matching result.
    * @param callId - the call id the matching `tool/result` will look up.
    * @param name - the tool name, resolved against the registry for `presentCall`.
-   * @param argsJson - the raw arguments JSON from the event; parsed for the view
-   * (a non-JSON string is surfaced raw).
-   * @returns the tool-owned view, or a generic parsed-input fallback.
+   * @param argsJson - raw event arguments parsed for presentation.
+   * @returns the tool-owned view or generic fallback.
    */
   call(callId: CallId, name: string, argsJson: string): ToolCallView {
     const args = parseToolArguments(argsJson)
@@ -1198,22 +1172,20 @@ export class ToolPresenter {
       this.onError(`acp: tool "${name}" presentCall threw, using generic presentation: ${String(error)}`)
       present = undefined
     }
-    // No tool-owned presentation: fall back to the tool name as the title, the
-    // full parsed args as the raw input, and kind `other` (the generic card).
-    // The kind is never sniffed from the name — the bridge does not special-case
-    // tool names; a tool that wants a richer kind declares `presentCall`.
+    // Tool names never imply presentation kind; richer cards are tool-owned.
     const view: ToolCallView = present ?? { card: 'generic', title: name, kind: 'other', rawInput: args }
     this.pending.set(callId, { name, args, card: view.card })
     return view
   }
 
   /**
-   * Resolve a completed result and consume its remembered call state.
+   * Completed-state render intent for a `tool/result`; consumes the remembered
+   * `(name, args, card)`.
    * @param callId - matching call id; unknown or late ids use raw content.
-   * @param content - the result's content blocks (the fallback and fill-in body).
+   * @param content - result content used by the fallback and fill-in body.
    * @param isError - whether the result is an error, forwarded to `presentResult`.
    * @param meta - the result's machine-readable meta, forwarded when present.
-   * @returns the normalized tool-owned view, or a raw-content generic fallback.
+   * @returns a normalized tool-owned view or raw-content fallback.
    */
   result(callId: CallId, content: ContentBlock[], isError: boolean, meta?: unknown): ToolResultView {
     const call = this.pending.get(callId)
@@ -1283,11 +1255,11 @@ type AcpToolCallContent =
   | { type: 'diff'; path: string; oldText: string | null; newText: string }
   | { type: 'terminal'; terminalId: string }
 
-/** Relativize an in-workspace file path in a card title; keep target paths raw. */
+/** Relativize only in-workspace title text; location and diff paths stay raw. */
 function displayTitle(title: string, rawPath: string | undefined, sessionCwd: string | undefined): string {
   if (rawPath === undefined || sessionCwd === undefined || !isAbsolute(rawPath) || !isAbsolute(sessionCwd)) return title
   const rel = relativePath(sessionCwd, rawPath)
-  // Reject an empty relative path or a leading parent-directory segment.
+  // Test the `..` segment, not a character prefix: `..cache/x` is in-workspace.
   if (rel.length === 0 || rel === '..' || rel.startsWith(`..${pathSep}`)) return title
   return title.split(rawPath).join(rel)
 }

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)

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')
   })
 

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,

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()
   })

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))

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/)
   })

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).

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)