Merge remote-tracking branch 'origin/master' into worktree/web-multimodal-image-input

# Conflicts: # .agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml # .agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md # .agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md # .agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.i18n.yaml # .agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md # .agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md # THIRD_PARTY_NOTICES.md # apps/cli/composition.md # apps/cli/config/base.cordis.yml # apps/cli/package.json # apps/cli/src/app-cli-entry.ts # apps/cli/src/bin.ts # apps/cli/tests/args.spec.ts # apps/web/tests/built-boot.snapshot.ts # apps/web/tests/navigation-panes.e2e.ts # docs/architecture.i18n.yaml # docs/architecture.md # docs/architecture.zh.md # docs/config-catalog.md # docs/cordis-catalog/services.md # docs/core-data-structures/core.i18n.yaml # docs/core-data-structures/llm-streaming.i18n.yaml # docs/event-producer-consumer.md # docs/module-graph.md # examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl # packages/README.i18n.yaml # packages/bundle/README.i18n.yaml # packages/client/connection/README.i18n.yaml # packages/client/connection/README.md # packages/client/connection/README.zh.md # packages/client/connection/src/client/fixture.ts # packages/client/connection/src/http-bridge.ts # packages/client/connection/src/index.ts # packages/client/connection/tests/fixture.spec.ts # packages/client/connection/tests/node-half.spec.ts # packages/client/runtime/README.i18n.yaml # packages/client/runtime/README.md # packages/client/runtime/README.zh.md # packages/client/runtime/src/client/contract/session.ts # packages/client/runtime/src/client/sessions/session.ts # packages/client/ui-conversation/README.i18n.yaml # packages/client/ui-conversation/README.md # packages/client/ui-conversation/README.zh.md # packages/client/ui-conversation/src/client/apply.ts # packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx # packages/client/ui-conversation/src/client/chat/ChatView.tsx # packages/client/ui-conversation/src/client/chat/MessageItem.module.css # packages/client/ui-conversation/src/client/chat/MessageItem.tsx # packages/client/ui-conversation/src/client/contract/slots.ts # packages/client/ui-conversation/src/client/index.ts # packages/client/ui-conversation/src/client/input/contract.ts # packages/client/ui-conversation/src/client/input/facade.ts # packages/client/ui-conversation/src/client/input/hub.ts # packages/client/ui-conversation/src/client/locales.ts # packages/client/ui-conversation/src/client/service.ts # packages/client/ui-conversation/src/client/skeleton/ConversationSession.tsx # packages/client/ui-conversation/src/client/skeleton/InputBar.tsx # packages/client/ui-conversation/tests/apply-inject.spec.tsx # packages/client/ui-conversation/tests/input-bar.spec.tsx # packages/client/ui-conversation/tests/input-matrix.spec.tsx # packages/client/ui-conversation/tests/input-scenarios.spec.tsx # packages/client/ui-conversation/tests/service-orchestration.spec.ts # packages/client/ui-conversation/tests/skeleton.spec.tsx # packages/client/ui-trajectory/tests/views.spec.tsx # packages/compact/compact-basic/README.i18n.yaml # packages/cordis/tool-cordis/src/api-catalog.ts # packages/host/apiproxy/README.i18n.yaml # packages/host/apiproxy/README.md # packages/host/apiproxy/README.zh.md # packages/host/apiproxy/src/api-proxy.ts # packages/host/apiproxy/src/api/rpc.ts # packages/host/apiproxy/src/api/sessions.ts # packages/host/apiproxy/src/index.ts # packages/host/apiproxy/tests/api-proxy-models.spec.ts # packages/host/apiproxy/tests/rpc-schemas.spec.ts # packages/llm/llm-pi-ai/README.i18n.yaml # packages/llm/llm-pi-ai/README.md # packages/llm/llm-pi-ai/README.zh.md # packages/llm/llm-pi-ai/src/adapter.ts # packages/llm/llm/README.i18n.yaml # packages/ui/tui/README.md # packages/ui/tui/README.zh.md # packages/ui/tui/src/components/content.ts # packages/ui/tui/src/components/transcript.ts # packages/ui/tui/tests/tui.spec.ts # pnpm-lock.yaml
2026-08-08 01:56:29 +08:00
parent 78d956a65d 698d65de2d
commit 25d959aa08
3973 changed files with 144864 additions and 60887 deletions
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/acp/README.md
-README.md: 326615210e5cfc39004fc5ab7462623089ac4126
-README.zh.md: 8679f2428a9e82a81de69d7d1413132a946fcafa
+README.md: 3ba247598f29f2244456061fe7f9a3282086148f
+README.zh.md: c13bc05b12fff2ef97b4d547936aa14a6556430a
@@ -6,6 +6,6 @@ The ACP group exposes harness agents to programmatic clients. It is an interoper

 | Package | Role |
 |---|---|
-| [`acp/`](acp/README.md) | Automation-only ACP server: fresh text sessions, committed assistant output, machine permission policy, cancellation, and connection-owned teardown. |
+| [`acp/`](acp/README.md) | Automation-only ACP server. |

 The matching out-of-process subagent client remains in [`subagent/subagent-acp`](../subagent/subagent-acp/README.md) because it implements the subagent provider interface; arbitrary ACP clients may drive the same server contract.
@@ -6,6 +6,6 @@ ACP（Agent Client Protocol）组将 harness 中的 agent（智能体）公开

 | 包 | 职责 |
 |---|---|
-| [`acp/`](acp/README.md) | 仅面向自动化的 ACP 服务器：新文本会话、已提交的 assistant 输出、机器权限策略、取消和由连接负责的清理。 |
+| [`acp/`](acp/README.md) | 仅面向自动化的 ACP 服务器。 |

 与之匹配的进程外 subagent 客户端仍位于 [`subagent/subagent-acp`](../subagent/subagent-acp/README.md)，因为它实现 subagent 提供方接口；任意 ACP 客户端都可以按照同一服务器契约驱动该服务器。
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/acp/acp/README.md
-README.md: 1b188b994d17ce56e8d5df019ddef755338fcc88
-README.zh.md: c1e7d045b55119b62ad44d81071188e1ed6110d5
+README.md: 9cc4a5e271c7200f6ad8799a4b8fa9e64b2ca893
+README.zh.md: 82aa5df2c7d87312d4b619a09582cc0c2d884398
@@ -4,7 +4,7 @@ English | [中文](README.zh.md)

 Automation-only [Agent Client Protocol](https://agentclientprotocol.com) server over JSON-RPC stdio. Programmatic clients create fresh harness agents, send text prompts, collect committed assistant text, resolve one-shot permission requests by policy, and cancel work. The primary in-repository client is [`dsh-subagent-acp`](../../subagent/subagent-acp/README.md).

-This package is a transport adapter, not a UI integration or a capability seam. It does not expose editor navigation, transcript replay, commands, modes, configuration pickers, elicitation, reasoning, plans, titles, or tool presentation. Interactive rendering and human questions belong to the web and TUI modules.
+This package is a transport adapter, not a UI integration or a capability seam. It does not expose editor navigation, transcript replay, commands, modes, configuration pickers, elicitation, reasoning, plans, titles, or tool presentation. Interactive rendering and human questions belong to the Web host and client modules.

 ## Plugin

@@ -24,7 +24,7 @@ Both fields are optional so another agent/request listener may supply the target
 | `initialize` | Negotiates the supported version and advertises baseline-only prompts (no image, audio, or embedded-context capability). No session, editor, terminal, filesystem, or MCP capability is advertised. |
 | `authenticate` | No-op because the server advertises no authentication methods. |
 | `session/new` | Creates a fresh agent with an absolute primary `cwd`; empty `additionalDirectories` and `mcpServers` are accepted, non-empty values reject. |
-| `session/prompt` | Concatenates text blocks, renders baseline resource links as bracketed textual references, rejects empty or beyond-baseline input, permits one in-flight request per session, and settles from that request's owning durable `turn/end`. |
+| `session/prompt` | Concatenates text blocks, renders baseline resource links as bracketed textual references, rejects empty or beyond-baseline input, permits one in-flight request per session, and waits for the whole agent to become idle. Normal quiescence reports `end_turn`; explicit ACP cancellation, disposal, or a prompt whose admission was discarded (a turnless slot) reports `cancelled`. |
 | `session/cancel` | Cancels only the addressed agent and settles its pending prompt as `cancelled`; unknown ids are no-ops. |
 | `session/update` | Emits one `agent_message_chunk` per non-empty text block in a committed `assistant/message`. Raw deltas and non-message events are omitted. |
 | `session/request_permission` | Offers one-shot allow/reject choices for bridge-owned approval requests carrying a tool call id. Clients may answer automatically. |
@@ -35,7 +35,9 @@ Committed-message output intentionally trades token-by-token latency for a clean

 ## Lifecycle

-Client disconnect and Cordis disposal share one memoized teardown. The bridge first rejects new sessions and prompts, settles pending prompts, then disposes all owned agent handles in parallel and awaits their loop/session cleanup. An ACP-only plugin reload therefore leaves no orphan agent.
+Client disconnect and Cordis disposal share one memoized teardown. The bridge first rejects new sessions and prompts, settles pending prompts, then drains continuable descendants only below this connection's exact owned Agents before disposing those handles in parallel and awaiting every result before reporting any failure. Other frontends sharing the Context retain their continuable forests and admission. An ACP-only plugin reload therefore leaves no orphan agent.
+
+ACP requires each prompt response to carry a `stopReason`, but the bridge does not claim a prompt-specific turn outcome. Committed assistant messages stream across the owned activity, and steering or injected work may contribute before idle. Token-limit turn endings therefore do not become prompt-level ACP stop reasons (they settle as `end_turn`); a model error on the correlated turn rejects the prompt immediately.

 ## Running

@@ -4,7 +4,7 @@

 通过 JSON-RPC stdio 提供的仅面向自动化的 [ACP（Agent Client Protocol）](https://agentclientprotocol.com) 服务器。程序化客户端可以创建新 harness agent（智能体）、发送文本提示词、收集已提交的 assistant 文本、按策略响应一次性权限请求并取消工作。仓库中的主要客户端是 [`dsh-subagent-acp`](../../subagent/subagent-acp/README.md)。

-此包（package）是传输适配器，而非 UI 集成或能力 seam。它不公开编辑器导航、transcript（文本记录）回放、命令、模式、配置选择器、信息征集、推理、计划、标题或工具展示。交互式渲染与向用户提问属于 Web 和 TUI 模块。
+此包是传输适配器，而非 UI 集成或能力 seam。它不公开编辑器导航、transcript（文本记录）回放、命令、模式、配置选择器、信息征集、推理（reasoning）、计划、标题或工具展示。交互式渲染与向用户提问属于 Web 宿主和客户端模块。

 ## 插件

@@ -24,7 +24,7 @@
 | `initialize` | 协商受支持的版本，并仅公布基线提示词（无图像、音频或嵌入上下文能力）。不公布会话、编辑器、终端、文件系统或 MCP 能力。 |
 | `authenticate` | 空操作，因为服务器不公布身份验证方法。 |
 | `session/new` | 以绝对路径作为主 `cwd` 创建新 agent；接受空的 `additionalDirectories` 和 `mcpServers`，拒绝非空值。 |
-| `session/prompt` | 拼接文本块，将基线资源链接渲染为带方括号的文本引用，拒绝空输入或超出基线的输入，每个会话只允许一个正在处理的请求，并根据该请求所属的持久 `turn/end` 结算。 |
+| `session/prompt` | 拼接文本块，将基线资源链接渲染为带方括号的文本引用，拒绝空输入或超出基线的输入，每个会话只允许一个正在处理的请求，并等待整个 agent 进入 idle。正常完全停稳时报告 `end_turn`；显式 ACP 取消、资源释放，或准入被丢弃的提示词（turnless 槽位）时报告 `cancelled`。 |
 | `session/cancel` | 仅取消指定的 agent，并将其待处理提示词结算为 `cancelled`；未知 id 为空操作。 |
 | `session/update` | 为每个非空文本块发出一个 `agent_message_chunk`；这些文本块来自已提交的 `assistant/message`。省略原始增量和非消息事件。 |
 | `session/request_permission` | 为携带工具调用 id、由桥接层拥有的批准请求提供一次性允许／拒绝选项。客户端可以自动回答。 |
@@ -35,7 +35,9 @@

 ## 生命周期

-客户端断开连接与 Cordis 的 dispose（资源释放）共用同一个记忆化清理流程。桥接层先拒绝新会话和提示词，结算待处理提示词，然后并行对其拥有的全部 agent 句柄执行 dispose，并等待它们的循环／会话清理完成。因此，单独重载 ACP 插件不会遗留孤儿 agent。
+客户端断开与 Cordis 释放共用同一个记忆化清理流程。桥接层先拒绝新会话和提示词，结算待处理提示词，然后只 drain 此连接确切拥有的 Agent 之下的可继续后代，再并行释放这些 handle，并等待全部结果结算后才报告失败。其他共享该上下文的前端会保留其可继续森林和准入。因此，仅 ACP 的插件重载不会遗留 agent。
+
+ACP 要求每个提示词响应都携带 `stopReason`，但桥接层不声称它表示提示词专属的轮次结果。已提交的 assistant 消息会在整个自有活动期间流式输出，agent 进入 idle 前发生的 steering（中途引导）或注入工作也可能参与其中。因此，因 token 上限而结束的轮次不会成为提示词级 ACP 停止原因（它们以 `end_turn` 结算）；关联轮次上的模型错误会立即 reject 提示词。

 ## 运行

@@ -47,7 +49,7 @@

 #### 模型看到的内容

-`session/prompt` 文本块会原样拼接为一条用户消息；基线资源链接会在该消息中表示为带方括号的 `[resource_link name=… uri=…]` 引用，模型可以使用自身工具打开它。协议元数据、客户端能力、权限选择和 session id 绝不进入模型请求。
+`session/prompt` 文本块会原样拼接为一条用户消息；基线资源链接会在该消息中表示为带方括号的 `[resource_link name=… uri=…]` 引用，模型可以使用自身工具打开它。协议元数据、客户端能力、权限选择和会话 id 绝不进入模型请求。

 #### Token 影响

@@ -65,11 +67,11 @@

 #### Token 影响

-只有该工具的结果会贡献 token。
+只有所属工具的结果会贡献 token。

 #### KV Cache 影响

-随该工具的结果仅追加。
+仅通过所属工具的结果追加。

 ## 已知限制与暂缓事项

@@ -21,9 +21,7 @@
  "files": [
    "lib/index.js",
    "lib/invariant.js",
-    "lib/types/**/*.d.ts",
-    "lib/types/**/*.d.ts.map",
-    "src"
+    "lib/types/**/*.d.ts"
  ],
  "license": "BSD-3-Clause",
  "dependencies": {
@@ -17,13 +17,17 @@ export function turnEndToStopReason(reason: TurnEndReason): StopReason {
      return 'end_turn'
    case 'max-tokens':
      return 'max_tokens'
+    // `cancelled` is reserved for explicit client cancellation (`session/cancel`)
+    // and disposal, both settled out of band; a turn aborted by a hook or
+    // another owner is ordinary quiescence and reports `end_turn`.
    case 'aborted':
-    case 'disposed':
+      return 'end_turn'
    case 'interrupted':
      return 'cancelled'
+    case 'blocked':
    case 'error':
      return 'end_turn'
-    // TurnEndReason is merge-extensible; future variants still need a legal wire value.
+    /* v8 ignore next 2 -- TurnEndReason is closed and every member is handled above */
    default:
      return 'end_turn'
  }
@@ -14,7 +14,7 @@ import { randomUUID } from 'node:crypto'
 import { isAbsolute } from 'node:path'
 import { Readable, Writable } from 'node:stream'
 import Schema from 'schemastery'
-import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import { createUserMessage, errorChain } from '@deepseek-ai/dsh-llm'
 import {
  AgentSideConnection,
  ndJsonStream,
@@ -43,6 +43,19 @@ export const name = 'acp'
 /** The bridge creates and owns agents; every other concern is carried by the agent composition. */
 export const inject = ['agents']

+/**
+ * The single continuable-subagent teardown the bridge needs. Declared
+ * structurally so this package does not depend on the subagent seam for one
+ * shutdown hook; an absent service means nothing continuable was materialized.
+ */
+interface ContinuableDrain {
+  /**
+   * Close admission below exact host-owned parents, then dispose only their
+   * continuable descendants child-first.
+   */
+  drainContinuableDescendants(parents: readonly Agent[]): Promise<void>
+}
+
 /** Preserve invalid-parameter detail in the SDK wire error message. */
 function invalidParams(detail: string): RequestError {
  return RequestError.invalidParams(undefined, detail)
@@ -77,13 +90,10 @@ interface SessionRecord {
  inflight: {
    resolve: (reason: StopReason) => void
    reject: (error: Error) => void
+    messageId: string
    turn: number | undefined
-    /**
-     * A failed turn's terminal reason, held until quiescence: a retry action
-     * closes the failed turn and opens a successor that adopts the prompt, so
-     * rejecting at `turn/end` would race the recovery.
-     */
-    pendingError: Extract<TurnEndReason, { kind: 'error' }> | undefined
+    /** The correlated turn's ending, set at turn/end and settled at whole-agent idle. */
+    endReason: TurnEndReason | undefined
  } | undefined
 }

@@ -136,7 +146,7 @@ export function apply(ctx: Context, config: AcpConfig): void {
    inflight: NonNullable<SessionRecord['inflight']>,
    reason: Extract<TurnEndReason, { kind: 'error' }>,
  ): void => {
-    inflight.reject(internalError(`turn failed: ${'failure' in reason ? reason.failure.message : reason.message}`))
+    inflight.reject(internalError(`turn failed: ${reason.error.message}`))
  }

  // Emit only committed assistant text. Raw chunks, reasoning, tools, plans,
@@ -172,30 +182,33 @@ export function apply(ctx: Context, config: AcpConfig): void {
      }
    } finally {
      const inflight = record.inflight
-      if (inflight !== undefined && event.type === 'turn/start') {
-        if (inflight.turn === undefined && event.data.trigger.kind === 'message'
-          && event.data.trigger.source.kind === 'user') {
-          inflight.turn = event.data.turn
-        } else if (inflight.pendingError !== undefined && event.data.trigger.kind === 'retry') {
-          // A recovery policy opened a retry turn on the failed history: the
-          // prompt rides it instead of rejecting on the failed turn's end.
-          inflight.turn = event.data.turn
-          inflight.pendingError = undefined
-        }
-      } else if (inflight !== undefined && event.type === 'turn/end' && inflight.turn === event.data.turn) {
+      if (inflight !== undefined && event.type === 'turn/end' && inflight.turn === event.data.turn) {
        if (event.data.reason.kind === 'error') {
-          // Hold the rejection: request recovery may adopt the prompt with a
-          // successor turn; quiescence without one delivers this error.
-          inflight.turn = undefined
-          inflight.pendingError = event.data.reason
-        } else {
+          // Model failures surface immediately as prompt errors; ordinary
+          // endings wait for whole-agent idle below.
          record.inflight = undefined
-          inflight.resolve(turnEndToStopReason(event.data.reason))
+          rejectFromError(inflight, event.data.reason)
+        } else {
+          inflight.endReason = event.data.reason
        }
      }
    }
  })

+  ctx.on('agent/inbox/claimed', ({ agent, message, turn }) => {
+    const record = ownedRecord(agent)
+    const inflight = record?.inflight
+    if (inflight !== undefined && inflight.messageId === message.id) inflight.turn = turn
+  })
+
+  ctx.on('agent/error', ({ agent, turn, error }) => {
+    const record = ownedRecord(agent)
+    const inflight = record?.inflight
+    if (record === undefined || inflight === undefined || inflight.turn === turn) return
+    record.inflight = undefined
+    inflight.reject(internalError(`turn failed: ${errorChain(error)}`))
+  })
+
  // Permission requests are a machine policy channel for ACP clients such as
  // dsh-subagent-acp. The bridge offers one-shot choices only and never infers a
  // durable grant from an unknown client response.
@@ -276,17 +289,18 @@ export function apply(ctx: Context, config: AcpConfig): void {
        if (ctx.agents.get(record.agent.id) !== record.agent) {
          throw internalError('prompt was not queued: the agent was disposed outside the bridge')
        }
+        const message = createUserMessage({ content: [{ type: 'text', text }], source: { kind: 'user' } })
        const stopReason = await new Promise<StopReason>((resolve, reject) => {
          // Arm the slot before followup() so a listener-driven synchronous
          // turn cannot slip past correlation; a synchronous followup()
          // failure (invalid input) must free the slot again or the session
          // would reject every later prompt as already in flight.
          const inflight: NonNullable<SessionRecord['inflight']> = {
-            resolve, reject, turn: undefined, pendingError: undefined,
+            resolve, reject, messageId: message.id, turn: undefined, endReason: undefined,
          }
          record.inflight = inflight
          try {
-            record.agent.followup(createUserMessage({ content: [{ type: 'text', text }], source: { kind: 'user' } }))
+            record.agent.followup(message)
            // The machine's send() contains listener failures and accepts
            // any typed input; this guards a future synchronous throw so the
            // slot cannot wedge.
@@ -297,18 +311,21 @@ export function apply(ctx: Context, config: AcpConfig): void {
            throw internalError(`prompt was not queued: ${detail}`)
          }
          /* v8 ignore stop */
-          // Admission is pre-turn and retries outlive their failed turn, so a
-          // turnless slot settles only at quiescence: a held failure rejects
-          // (no retry adopted the prompt); no turn at all means admission
-          // discarded the prompt — report cancelled.
+          // Settlement waits for whole-agent idle: a correlated turn/end arms
+          // `endReason`, while a turnless slot (admission discarded the
+          // prompt) stays cancelled. Other producers may run further turns
+          // before quiescence; the prompt settles only when the agent stops.
          void record.agent.whenIdle().then(() => {
-            if (record.inflight !== inflight || inflight.turn !== undefined) return
+            if (record.inflight !== inflight) return
            record.inflight = undefined
-            if (inflight.pendingError !== undefined) {
-              rejectFromError(inflight, inflight.pendingError)
-              return
+            const end = inflight.endReason
+            if (end === undefined) {
+              inflight.resolve('cancelled')
+            } else {
+              // Token-limit and other non-terminal endings are not prompt-level
+              // stop reasons (see README); only normal quiescence reports end_turn.
+              inflight.resolve(end.kind === 'max-tokens' ? 'end_turn' : turnEndToStopReason(end))
            }
-            inflight.resolve('cancelled')
          })
        })
        return { stopReason }
@@ -337,10 +354,45 @@ export function apply(ctx: Context, config: AcpConfig): void {
    closed = true
    const records = [...sessions.values()]
    sessions.clear()
-    quiescing = Promise.all(records.map(async (record) => {
+    // Stop the bridge's own work before any await: a descendant drain can block
+    // on persistence or scoped cleanup, and the top-level agents must not keep
+    // running model and tool calls for its whole duration.
+    for (const record of records) {
+      record.agent.cancel({ kind: 'user' })
      settlePrompt(record, 'cancelled')
-      await record.dispose()
-    })).then(() => {})
+    }
+    quiescing = (async () => {
+      // Continuable subagents outlive the turn that started them, and their
+      // Activations own descendant teardown. Drain only these sessions' forests
+      // child-first BEFORE disposing the top-level agents, so no descendant is
+      // left holding a runtime its owner already released and another frontend
+      // sharing this Context remains live.
+      // Read the one teardown method structurally: the bridge needs no other
+      // part of the subagent seam, so it does not depend on that package.
+      const subagents = ctx.get('subagents') as ContinuableDrain | undefined
+      if (subagents !== undefined) {
+        try {
+          await subagents.drainContinuableDescendants(records.map(record => record.agent))
+        } catch (error: unknown) {
+          logger.warn(`acp: continuable subagent teardown failed: ${String(error)}`)
+        }
+      }
+      const disposals = await Promise.allSettled(records.map(record => record.dispose()))
+      const failures: unknown[] = []
+      for (const result of disposals) {
+        if (result.status === 'rejected') failures.push(result.reason as unknown)
+      }
+      if (failures.length > 0) {
+        // The production consumer logs this AggregateError through `String`,
+        // which renders only its message. Embed every per-session diagnostic,
+        // including nested causes and aggregate members, in that message.
+        const detail = failures.map(failure => errorChain(failure)).join('; ')
+        throw new AggregateError(
+          failures,
+          `ACP agent teardown failed for ${failures.length} session(s): ${detail}`,
+        )
+      }
+    })()
    return quiescing
  }

@@ -20,7 +20,7 @@ describe('ACP machine permission policy', () => {
    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
    const agent = harness.ctx.agents.get(SessionId(sessionId))!
-    agent.session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    agent.session.append('turn/start', { turn: 1 })
    return { agent, toolName: 'bash', callId: CallId('call-9'), ...overrides }
  }

@@ -1,37 +1,24 @@
 import { describe, expect, it } from 'vitest'
 import type { TurnEndReason } from '@deepseek-ai/dsh-session'
-import { acpPromptToText, promptHasUnsupportedContent, turnEndToStopReason } from '../src/codec.ts'
+import { acpPromptToText, turnEndToStopReason } from '../src/codec.ts'

-describe('ACP automation codec', () => {
-  it('maps every known turn outcome to a legal stop reason', () => {
-    const cases: [TurnEndReason, string][] = [
-      [{ kind: 'completed' }, 'end_turn'],
-      [{ kind: 'max-tokens' }, 'max_tokens'],
-      [{ kind: 'aborted' }, 'cancelled'],
-      [{ kind: 'disposed' }, 'cancelled'],
-      [{ kind: 'interrupted' }, 'cancelled'],
-      [{ kind: 'error', step: 1, message: 'boom' }, 'end_turn'],
-    ]
-    for (const [reason, expected] of cases) expect(turnEndToStopReason(reason)).toBe(expected)
+describe('ACP codec', () => {
+  it.each([
+    [{ kind: 'completed' }, 'end_turn'],
+    [{ kind: 'max-tokens' }, 'max_tokens'],
+    [{ kind: 'aborted', reason: { kind: 'user' } }, 'end_turn'],
+    [{ kind: 'interrupted' }, 'cancelled'],
+    [{ kind: 'blocked' }, 'end_turn'],
+    [{ kind: 'error', error: { message: 'failed', code: 'UNKNOWN' } }, 'end_turn'],
+  ] satisfies Array<[TurnEndReason, string]>)('maps %o to %s', (reason, expected) => {
+    expect(turnEndToStopReason(reason)).toBe(expected)
  })

-  it('uses a legal fallback for merge-extensible future outcomes', () => {
-    expect(turnEndToStopReason({ kind: 'future' } as unknown as TurnEndReason)).toBe('end_turn')
-  })
-
-  it('flattens baseline blocks and rejects everything richer', () => {
-    expect(acpPromptToText([{ type: 'text', text: 'a' }, { type: 'text', text: 'b' }])).toBe('ab')
-    expect(acpPromptToText([
-      { type: 'text', text: 'see' },
-      { type: 'resource_link', name: 'x', uri: 'file:///x' },
-    ])).toBe('see\n[resource_link name="x" uri="file:///x"]\n')
-    expect(acpPromptToText([{ type: 'image', data: '', mimeType: 'image/png' }])).toBe('')
-    expect(promptHasUnsupportedContent([
-      { type: 'text', text: 'ok' },
-      { type: 'resource_link', name: 'x', uri: 'file:///x' },
-    ])).toBe(false)
-    expect(promptHasUnsupportedContent([
-      { type: 'image', data: '', mimeType: 'image/png' },
-    ])).toBe(true)
+  it('drops unsupported blocks from baseline text conversion', () => {
+    expect(acpPromptToText([{
+      type: 'image',
+      data: '',
+      mimeType: 'image/png',
+    }])).toBe('')
  })
 })
@@ -1,5 +1,6 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk'
+import type { Agent } from '@deepseek-ai/dsh-agent'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import { makeBridgeHarness, type BridgeHarness } from './harness.ts'

@@ -25,6 +26,137 @@ describe('ACP connection ownership', () => {
    expect(harness.ctx.agents.get(SessionId(sessionId))).toBeUndefined()
  })

+  it('drains continuable subagents before disposing its own sessions', async () => {
+    harness = await makeBridgeHarness()
+    const order: string[] = []
+    let drainedParents: readonly Agent[] = []
+    // A continuable Activation outlives the turn that started it, so the bridge
+    // must release that forest before the agents whose runtime it depends on.
+    harness.ctx.provide('subagents', {
+      drainContinuableDescendants: (parents: readonly Agent[]) => {
+        drainedParents = parents
+        order.push('drained')
+        return Promise.resolve()
+      },
+    } as never)
+    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
+    const agent = harness.ctx.agents.get(SessionId(sessionId))!
+    harness.ctx.on('agent/disposed', () => { order.push('agent disposed') })
+
+    await harness.acpFiber.dispose()
+
+    expect(order).toEqual(['drained', 'agent disposed'])
+    expect(drainedParents).toEqual([agent])
+    expect(harness.ctx.agents.get(SessionId(sessionId))).toBeUndefined()
+  })
+
+  it('cancels its own prompt before awaiting the descendant drain', async () => {
+    harness = await makeBridgeHarness({ script: ['hang'] })
+    const order: string[] = []
+    const release = Promise.withResolvers<undefined>()
+    harness.ctx.provide('subagents', {
+      drainContinuableDescendants: async () => {
+        order.push('drain started')
+        await release.promise
+        order.push('drain finished')
+      },
+    } as never)
+    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
+    const agent = harness.ctx.agents.get(SessionId(sessionId))!
+    void harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] }).catch(() => {})
+    await vi.waitFor(() => { expect(agent.status).toBe('running') })
+    const cancel = agent.cancel.bind(agent)
+    let cancelObserved = false
+    vi.spyOn(agent, 'cancel').mockImplementation((...args) => {
+      if (!cancelObserved) {
+        cancelObserved = true
+        order.push('parent cancelled')
+      }
+      cancel(...args)
+    })
+
+    const disposal = harness.acpFiber.dispose()
+    // A drain can block on persistence, so the bridge's own turn must already be
+    // cancelled rather than running for its whole duration.
+    await vi.waitFor(() => { expect(order).toContain('drain started') })
+    expect(order).toEqual(['parent cancelled', 'drain started'])
+    release.resolve(undefined)
+    await disposal
+    expect(harness.ctx.agents.get(SessionId(sessionId))).toBeUndefined()
+  })
+
+  it('reports a failed continuable drain and still disposes its sessions', async () => {
+    harness = await makeBridgeHarness()
+    const warnings: string[] = []
+    harness.ctx.logger.warn = (message: string) => { warnings.push(message) }
+    harness.ctx.provide('subagents', {
+      drainContinuableDescendants: () => Promise.reject(new Error('activation teardown failed')),
+    } as never)
+    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
+
+    await harness.acpFiber.dispose()
+
+    // A stuck descendant must not strand the bridge's own teardown.
+    expect(warnings.some(warning => warning.includes('continuable subagent teardown failed'))).toBe(true)
+    expect(harness.ctx.agents.get(SessionId(sessionId))).toBeUndefined()
+  })
+
+  it('awaits every owned session disposal and reports nested failure reasons', async () => {
+    harness = await makeBridgeHarness()
+    const create = harness.ctx.agents.create.bind(harness.ctx.agents)
+    const releaseSecond = Promise.withResolvers<undefined>()
+    const warnings: string[] = []
+    let created = 0
+    let secondStarted = false
+    harness.ctx.logger.warn = (message: string) => { warnings.push(message) }
+    const createSpy = vi.spyOn(harness.ctx.agents, 'create').mockImplementation(async (options) => {
+      const handle = await create(options)
+      const originalDispose = handle.dispose.bind(handle)
+      if (created++ === 0) {
+        handle.dispose = async () => {
+          await originalDispose()
+          throw new AggregateError([
+            new Error('scope cleanup failed', { cause: new Error('sqlite busy') }),
+            new Error('hook cleanup failed'),
+          ], 'first session cleanup failed')
+        }
+      } else {
+        handle.dispose = async () => {
+          secondStarted = true
+          await releaseSecond.promise
+          await originalDispose()
+        }
+      }
+      return handle
+    })
+    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    const first = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
+    const second = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
+
+    await harness.closeClientTransport()
+    await vi.waitFor(() => { expect(secondStarted).toBe(true) })
+    expect(warnings.some(warning => warning.includes('connection-close teardown failed'))).toBe(false)
+
+    releaseSecond.resolve(undefined)
+    await vi.waitFor(() => {
+      expect(warnings.some(warning =>
+        warning.includes(
+          'ACP agent teardown failed for 1 session(s): '
+          + 'first session cleanup failed [scope cleanup failed: sqlite busy; hook cleanup failed]',
+        ))).toBe(true)
+      expect(harness!.ctx.agents.get(SessionId(first.sessionId))).toBeUndefined()
+      expect(harness!.ctx.agents.get(SessionId(second.sessionId))).toBeUndefined()
+    })
+
+    createSpy.mockRestore()
+    const disposed = harness
+    harness = undefined
+    await disposed.dispose().catch(() => undefined)
+  })
+
  it('an ACP-only reload rejects new sessions before creating an orphan', async () => {
    harness = await makeBridgeHarness()
    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
@@ -31,11 +31,13 @@ describe('ACP prompt lifecycle', () => {
    harness = undefined
  })

-  it('maps a max-token turn without losing its committed text', async () => {
+  it('maps a max-token turn to end_turn without losing its committed text', async () => {
    harness = await makeBridgeHarness({ script: [maxTokensResponse('cut off')] })
    const sessionId = await newSession(harness)
    const result = await harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] })
-    expect(result.stopReason).toBe('max_tokens')
+    // A token-limit turn ending is not a prompt-level stop reason (README):
+    // the prompt settles at whole-agent idle with end_turn.
+    expect(result.stopReason).toBe('end_turn')
    await vi.waitFor(() => { expect(messageText(harness!)).toBe('cut off') })
  })

@@ -78,12 +80,27 @@ describe('ACP prompt lifecycle', () => {

  it('rejects an ordinary plugin failure through the same prompt boundary', async () => {
    harness = await makeBridgeHarness({ script: [textResponse('must not run')] })
-    harness.ctx.on('agent/step', () => { throw new Error('plugin pre-step failed') })
+    harness.ctx.on('agent/pre-step', () => { throw new Error('plugin pre-step failed') })
    const sessionId = await newSession(harness)
    await expect(harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] }))
      .rejects.toThrow(/turn failed: plugin pre-step failed/)
  })

+  it('rejects a turn-start failure before the prompt is claimed', async () => {
+    harness = await makeBridgeHarness({ script: [textResponse('must not run')] })
+    const sessionId = await newSession(harness)
+    const agent = harness.ctx.agents.get(SessionId(sessionId))!
+    const append = agent.session.append.bind(agent.session)
+    vi.spyOn(agent.session, 'append').mockImplementation(((type: string, ...rest: never[]) => {
+      if (type === 'turn/start') throw new Error('turn start unavailable')
+      return (append as (...args: never[]) => unknown)(type as never, ...rest)
+    }) as never)
+
+    await expect(harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] }))
+      .rejects.toThrow(/turn failed: turn start unavailable/)
+    vi.restoreAllMocks()
+  })
+
  it('settles even when an earlier turn observer throws', async () => {
    harness = await makeBridgeHarness({ script: [textResponse('answer')] })
    harness.ctx.on('session/event', (_session, event) => {
@@ -94,13 +111,13 @@ describe('ACP prompt lifecycle', () => {
      .resolves.toEqual({ stopReason: 'end_turn' })
  })

-  it('ignores an injection turn while correlating the owning message turn', async () => {
+  it('correlates the owning prompt when a synchronous injection joins its first step', async () => {
    harness = await makeBridgeHarness({ script: [textResponse('real answer')] })
    const sessionId = await newSession(harness)
    const agent = harness.ctx.agents.get(SessionId(sessionId))!
    let injected = false
-    harness.ctx.on('agent/inbox/enqueue', (subject) => {
-      if (subject === agent && !injected) {
+    harness.ctx.on('agent/inbox/inserted', ({ agent: subject, message }) => {
+      if (subject === agent && message.source.kind === 'user' && !injected) {
        injected = true
        agent.inject(createUserMessage({ content: [{ type: 'text', text: 'context' }], source: { kind: 'plugin', plugin: 'test' } }))
      }
@@ -115,30 +132,44 @@ describe('ACP prompt lifecycle', () => {
    harness = await makeBridgeHarness({ script: ['hang'] })
    const sessionId = await newSession(harness)
    const agent = harness.ctx.agents.get(SessionId(sessionId))!
-    let inserted = false
-    harness.ctx.on('agent/inbox/enqueue', (subject, item) => {
-      if (subject !== agent || item.message.source.kind !== 'user' || inserted) return
-      inserted = true
-      const source = { kind: 'plugin', plugin: 'test' } as const
-      agent.session.append('turn/start', { turn: 1, trigger: { kind: 'message', source } })
-      agent.session.append('user/message', createUserMessage({
-        content: [{ type: 'text', text: 'autonomous work' }],
-        source,
-      }), { surfaceOp: 'append' })
-      agent.session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    let autonomousStarted!: () => void
+    const started = new Promise<void>((resolve) => { autonomousStarted = resolve })
+    harness.ctx.on('session/event', (session, event) => {
+      if (session === agent.session && event.type === 'assistant/chunk') autonomousStarted()
    })
+    agent.followup(createUserMessage({
+      content: [{ type: 'text', text: 'autonomous work' }],
+      source: { kind: 'plugin', plugin: 'test' },
+    }))
+    await started

    let settled = false
    const prompt = harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] })
      .finally(() => { settled = true })
    await vi.waitFor(() => {
-      expect(agent.session.events.filter(event => event.type === 'turn/start')).toHaveLength(2)
+      expect(agent.session.events.filter(event => event.type === 'agent/inbox/spliced'
+        && event.data.inserted.length > 0)).toHaveLength(2)
    })
    expect(settled).toBe(false)
    await harness.client.cancel({ sessionId })
    await expect(prompt).resolves.toEqual({ stopReason: 'cancelled' })
  })

+  it('correlates a prompt whose step history is replaced', async () => {
+    harness = await makeBridgeHarness({ script: [textResponse('rewritten answer')] })
+    harness.ctx.on('agent/pre-step', async () => ({
+      kind: 'enter',
+      messages: [createUserMessage({
+        content: [{ type: 'text', text: 'rewritten prompt' }],
+        source: { kind: 'plugin', plugin: 'test' },
+      })],
+    }))
+    const sessionId = await newSession(harness)
+
+    await expect(harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'original' }] }))
+      .resolves.toEqual({ stopReason: 'end_turn' })
+  })
+
  it('frees the prompt slot when the agent rejects the send synchronously', async () => {
    harness = await makeBridgeHarness({ script: [] })
    const sessionId = await newSession(harness)
@@ -172,7 +203,39 @@ describe('ACP prompt lifecycle', () => {
    await harness.client.cancel({ sessionId })
    await expect(prompt).resolves.toEqual({ stopReason: 'cancelled' })
    await agent.whenIdle()
-    expect(agent.session.events.findLast(event => event.type === 'turn/end')?.data.reason).toEqual({ kind: 'aborted' })
+    expect(agent.session.events.findLast(event => event.type === 'turn/end')?.data.reason)
+      .toEqual({ kind: 'aborted', reason: { kind: 'user' } })
+  })
+
+  it('settles a hook-cancelled turn as end_turn, not cancelled', async () => {
+    harness = await makeBridgeHarness({ script: ['hang'] })
+    const sessionId = await newSession(harness)
+    const prompt = harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] })
+    const agent = harness.ctx.agents.get(SessionId(sessionId))!
+    await vi.waitFor(() => { expect(agent.status).toBe('running') })
+    // A hook or another owner cancels the agent: the ACP client never called
+    // session/cancel, so this is ordinary quiescence and reports end_turn.
+    agent.cancel({ kind: 'hook', reason: 'owner intervention' })
+    await expect(prompt).resolves.toEqual({ stopReason: 'end_turn' })
+  })
+
+  it('cancels autonomous running work without an in-flight prompt', async () => {
+    harness = await makeBridgeHarness({ script: ['hang'] })
+    const sessionId = await newSession(harness)
+    const agent = harness.ctx.agents.get(SessionId(sessionId))!
+    agent.followup(createUserMessage({
+      content: [{ type: 'text', text: 'autonomous work' }],
+      source: { kind: 'plugin', plugin: 'test' },
+    }))
+    await vi.waitFor(() => {
+      expect(agent.session.events.some(event => event.type === 'turn/start')).toBe(true)
+    })
+
+    await harness.client.cancel({ sessionId })
+    await agent.whenIdle()
+
+    expect(agent.session.events.findLast(event => event.type === 'turn/end')?.data.reason)
+      .toEqual({ kind: 'aborted', reason: { kind: 'user' } })
  })

  it('an idle cancel does not affect the following prompt', async () => {
@@ -201,7 +264,7 @@ describe('ACP prompt lifecycle', () => {
    harness = await makeBridgeHarness({ script: [errorResponse('transient boom'), textResponse('recovered')] })
    // A recovery policy: schedule one retry for the failed request.
    let retried = false
-    harness.ctx.on('agent/request-error', async (_subject) => {
+    harness.ctx.on('agent/request-error', async () => {
      if (!retried) {
        retried = true
        return { kind: 'retry' }
@@ -213,7 +276,7 @@ describe('ACP prompt lifecycle', () => {
    await vi.waitFor(() => { expect(messageText(harness!)).toBe('recovered') })
  })

-  it('a failed turn with no retry still rejects, at quiescence', async () => {
+  it('a failed turn with no retry still rejects', async () => {
    harness = await makeBridgeHarness({ script: [errorResponse('terminal boom')] })
    let offered = 0
    harness.ctx.on('agent/request-error', async () => { offered += 1 })
@@ -223,13 +286,36 @@ describe('ACP prompt lifecycle', () => {
    expect(offered).toBe(1)
  })

-  it('an admission-blocked prompt settles cancelled instead of hanging', async () => {
+  it('a pre-step-rejected prompt settles instead of hanging', async () => {
    harness = await makeBridgeHarness({ script: [] })
-    harness.ctx.on('agent/prompt-submit', async () => ({ kind: 'block' as const, reason: 'policy said no' }))
+    harness.ctx.on('agent/pre-step', async () => ({
+      kind: 'reject' as const,
+    }))
    const sessionId = await newSession(harness)
    await expect(harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] }))
-      .resolves.toEqual({ stopReason: 'cancelled' })
-    // The blocked prompt opened no turn and streamed nothing.
+      .resolves.toEqual({ stopReason: 'end_turn' })
+    // The rejected prompt closed a blocked turn without streaming anything.
    expect(messageText(harness)).toBe('')
  })
+
+  it('cancels a prompt removed before its turn claims it', async () => {
+    harness = await makeBridgeHarness({ script: [] })
+    const sessionId = await newSession(harness)
+    const dispose = harness.ctx.on('agent/inbox/inserted', ({ agent, message }) => {
+      if (message.source.kind === 'user') agent.inbox.remove(message.id)
+    })
+
+    await expect(harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] }))
+      .resolves.toEqual({ stopReason: 'cancelled' })
+    dispose()
+  })
+
+  it('rejects a prompt when pre-step fails inside its open turn', async () => {
+    harness = await makeBridgeHarness({ script: [] })
+    harness.ctx.on('agent/pre-step', async () => { throw new Error('pre-step exploded') })
+    const sessionId = await newSession(harness)
+
+    await expect(harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] }))
+      .rejects.toThrow(/turn failed: pre-step exploded/)
+  })
 })