@deepseek-ai/dsh-subagent-acp 0.1.1-rc.2 → 0.1.2-alpha.2

package/README.i18n.yaml

@@ -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/subagent/subagent-acp/README.md
-README.md: 3bccddbca021bed1f8bf5766b9575f3bd7441669
-README.zh.md: 7ae89ece0ce4282ad5b9a20142a2ba9b111f6d88
+README.md: 185a06a4003386a18414998e9cbaa314b9599921
+README.zh.md: 1594677f2ecdacd4ca389337fb29bd01ff18a108

package/README.md

@@ -1,73 +1,131 @@
+---
+description: "The out-of-process ACP subagent backend for users and maintainers choosing a delegation provider, configuring a child ACP agent command, or debugging remote child runs."
+kind: "package-reference"
+---
+
 # @deepseek-ai/dsh-subagent-acp
 
 English | [中文](README.zh.md)
 
-The ACP provider runs each subagent in a fresh subprocess and drives it as an Agent Client Protocol client. It is the out-of-process alternative to spawn and fork: the child has its own runtime, session, model configuration, and tools.
+## Summary
 
-## Start and ownership
+`dsh-subagent-acp` runs each delegated child in a fresh subprocess and drives it as an Agent Client Protocol client: the child gets its own runtime, session, model configuration, and tools, and it can be any ACP-compatible agent, not just Harness. It is the out-of-process alternative to the in-process spawn and fork backends, sharing only the parent session's working directory with the child. Each run spawns a fresh process, initializes an ACP session, sends the task, and collects the streamed final answer; permission prompts are auto-answered by configuration, so no human is needed. The parent receives only the child's final answer or a safe error — no intermediate messages or tool traffic crosses the boundary. Choose it when the child must be fully isolated from the parent harness and can speak ACP.
 
-`start(request)` resolves the child's working directory, then performs `spawn` → ACP `initialize` → `newSession` before it fulfills. Fulfillment therefore means a remote session is ready and ownership has transferred to the caller. A spawn, initialization, new-session, or pre-publication cancellation failure rejects only after the subprocess has been reaped; a working-directory resolution failure rejects before anything is spawned.
+## Table of Contents
 
-The working directory is the configured `cwd` override when set, else the delegating parent session's cwd — never the server process's own cwd, because one server process serves sessions from many workspaces. The parent-derived value must be an absolute path naming a directory the harness can enter (search permission — what a subprocess cwd needs), and the same resolved path becomes both the subprocess cwd and the ACP `session/new` workspace.
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
 
-The returned run id is minted in the parent namespace. The child server's session id remains private to ACP wire calls because ACP guarantees it only within that fresh child process; using it as the parent lifecycle id could collide with another remote run or a local agent.
+-----
 
-After publication, the provider sends the prompt and collects streamed `agent_message_chunk` text into `SubagentResult.output`. A prompt/transport failure resolves with `stopReason: 'error'`, or `aborted` when the required request signal or disposal requested cancellation.
+<a id="use-this-package"></a>
+## Use this package
 
-`dispose()` is idempotent. It removes the signal listener, requests ACP cancellation when possible, then runs this backend's own teardown ladder (`disposeAcpChild`) over the seam's verbs: close stdin and wait `disposeEofGraceMs` for cooperative quiescence, then invoke the handle's `terminate()` escalation (SIGTERM, the spawn grace, SIGKILL — Windows force-terminates directly) and await the subprocess owner's whole-tree exit proof. Every run uses a fresh process; process pooling is not implemented.
+Mount this provider when a composition needs a fully isolated, out-of-process child that speaks the Agent Client Protocol. The common path is explicit: mount the seam, mount this provider, and give it a command that starts an ACP agent.
 
-## Capabilities and context
+### When to choose it
 
-ACP advertises no start-time capabilities because this process cannot enforce the remote child's depth, tool filter, persona, or structured-output runtime. It also reports `inheritsParentContext: false`: the remote session starts fresh, and the only parent-derived input is the workspace cwd described above — no conversation context crosses the process boundary.
+Choose this backend when the child must run with its own runtime, model, and tools in a separate process — for example an ACP agent from another project — or when you want delegation that cannot touch the parent harness. Choose an in-process backend when the child must share the parent's composition or honor parent-enforced capabilities: this provider advertises no optional start-time capabilities, so the seam rejects requests for `agentOptions`, structured output, depth caps, tool filters, or personas rather than silently omitting them.
 
-## Configuration
+### Configuration
 
-| Key | Default | Meaning |
+| Field | Default | Meaning |
 |---|---|---|
-| `providerName` | `acp` | Registry name on `ctx.subagents`. |
-| `command` | required | Executable spawned for each run. |
-| `args` | `[]` | Command arguments. |
-| `cwd` | parent session cwd | Working-directory override for the child process and its ACP session; must be non-empty, a relative value resolves against the harness launch directory at load, and the result must name a directory the harness can enter. |
-| `permission` | `reject` | Auto-answer permission requests by rejecting or choosing the first `allow_once` or `allow_always` option. |
-| `env` | `{}` | Explicit child environment layered over a credential-scrubbed parent environment. |
-| `disposeEofGraceMs` | `6000` | Positive grace after stdin EOF before platform termination; it cannot exceed [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md). |
-| `disposeGraceMs` | `3000` | Positive POSIX grace after SIGTERM before SIGKILL (Windows force-terminates directly); it cannot exceed [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md). |
+| `providerName` | `acp` | Registry name on `ctx.subagents` |
+| `command` | required | Executable spawned for each run (the child ACP agent) |
+| `args` | `[]` | Command arguments |
+| `cwd` | parent session cwd | Working-directory override for the child process and its ACP session |
+| `permission` | `reject` | Auto-answer permission requests by rejecting, or choosing the first `allow_once` or `allow_always` option (`allow`) |
+| `env` | `{}` | Explicit child environment layered over the credential-scrubbed parent environment |
+| `disposeEofGraceMs` | `6000` | Grace after stdin EOF before platform termination |
+| `disposeGraceMs` | `3000` | Bound for observing structured process facts after failure and, on POSIX, the SIGTERM-to-SIGKILL grace |
+
+The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-subagent-acp) is the exhaustive source for every accepted field and its JSDoc.
+
+A DeepSeek Harness child uses the product launcher and an explicit absolute `DSH_HOME`. The isolated home prevents a nested runtime from discovering the launching person's profiles or credentials; the generic ACP provider does not impose this requirement on non-DSH agents.
 
 ```yaml
 - id: subagent-acp
   name: '@deepseek-ai/dsh-subagent-acp'
   config:
     providerName: acp
-    command: node
-    args: ['--import', 'tsx', './packages/examples/acp-demo/src/bin.ts', '--config', './examples/acp-agent/cordis.yml']
+    command: dsh
+    args: ['--profile', 'acp', '--patch', '/absolute/path/to/acp.patch.yml']
     permission: reject
     env:
+      DSH_HOME: /absolute/path/to/isolated-child-home
       DEEPSEEK_API_KEY: !!js process.env.DEEPSEEK_API_KEY
 ```
 
-## Stop-reason mapping
+### What you get
+
+A successful run returns the child's final streamed assistant text as the result output. The child's session, model, and tools come from the child process itself — the parent supplies only the task and the working directory. The stop reason maps `end_turn` to `completed`, `max_tokens` to `max-tokens`, `refusal` to `refusal`, `cancelled` to `aborted`, and every other value to `error`. A failed published run preserves partial assistant text in `output` and returns safe structured detail separately in `diagnostic`.
+
+### Failure and recovery
+
+A spawn, initialization, or new-session failure rejects before publication, ordinarily after the child process is reaped. If cleanup also fails, the rejection preserves ordered safe startup and teardown facts without claiming whole-tree quiescence. Non-cancellation errors expose only fixed provider, stage, and category facts; the original failure stays on the internal cause chain and in Host diagnostics. After publication, a prompt, transport, or early-process failure resolves as `error` with a safe diagnostic, while local cancellation resolves as `aborted` without failure detail.
+
+### Safe diagnostics
+
+A generic diagnostic uses one fixed line: `Subagent failure (provider: ACP; stage: <stage>; category: <category>; ...)`. Optional stop reason, exit code, and signal come only from closed protocol or managed-process facts. Stderr, exception text, task content, tool input, paths, environment values, credentials, and protocol payloads never enter the diagnostic; the shared result boundary limits it to 4096 UTF-8 bytes. A non-completed run that requested permission can add one fixed policy, tool-kind, and decision line. Successful runs and local cancellation omit it.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains how the backend drives a child over ACP and where the observable behavior comes from; the full contract lives in [Use this package](#use-this-package).
+
+### Design concept
+
+- **Full process isolation.** Each child runs in a fresh subprocess with its own session, model, and tools; only the resolved working directory crosses from the parent.
+- **One process per run.** Every run spawns a new process; there is no process pooling.
+- **The ACP wire is the serialization boundary.** Same-process subagent values are not defensively cloned; the protocol is where hostile input is validated.
+
+### Start and ownership flow
 
-| ACP | Harness |
-|---|---|
-| `end_turn` | `completed` |
-| `max_tokens` | `max-tokens` |
-| `refusal` | `refusal` |
-| `cancelled` | `aborted` |
-| `max_turn_requests` or unknown | `error` |
+A start resolves the child's working directory (the configured `cwd` override, else the parent session's cwd), spawns the command through the subprocess seam, performs the ACP `initialize` and `newSession` handshake, and only then publishes the run. Fulfillment means a remote session is ready and ownership has transferred to the caller. Disposal is idempotent: it closes stdin and waits a configured grace for cooperative quiescence, then escalates through SIGTERM to SIGKILL and awaits whole-tree exit. Cleanup failures remain observable as ordered safe facts and never claim quiescence.
 
-## Process boundary
+### Stop-reason mapping
 
-The child spawns through the [`dsh-subprocess`](../../subprocess/subprocess/README.md) seam: credential-shaped ambient variables and ambient `DSH_*` names are removed by the shared scrub, then explicit `config.env` values merge after it (an intended `DEEPSEEK_API_KEY` survives, and a `DSH_*` deployment fact such as `DSH_PERMISSION_MODE` reaches the child the same way — the scrub drops only its stale ambient namesake), stderr is inherited to the parent's own stream, and disposal applies this plugin's EOF window before the subprocess-owned SIGTERM→SIGKILL escalation and whole-tree join. The ACP wire is the real serialization boundary; same-process subagent values are not defensively cloned.
+The run outcome maps the ACP terminal into the shared stop-reason vocabulary (`completed`, `max-tokens`, `refusal`, `aborted`, or `error`) in [`src/run.ts`](src/run.ts).
 
-The package has no default export. Cordis loader unwrapping would otherwise hide the named `inject` metadata; see [postmortem 0001](../../../docs/postmortem/0001-acp-default-export-drops-inject.md).
+### Process boundary
 
+The child spawns through the subprocess seam: credential-shaped ambient variables are scrubbed, then explicit `config.env` values merge after the scrub. Stderr is inherited to the parent's stream, and disposal applies this provider's EOF window before the shared termination escalation.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the package-level contract is not enough. They move from this backend to the seam it plugs into and the protocol it drives.
+
+- [Subagent subsystem](../../../docs/subsystems/subagent.md) — the service contract, provider contract, and terminal result semantics.
+- [dsh-subagent seam](../subagent/README.md) — the registry and start API this provider registers on.
+- [Agent Client Protocol automation server](../../acp/acp/README.md) — the automation-only server this provider drives as a client.
+- [dsh-subprocess seam](../../subprocess/subprocess/README.md) — the process-spawn and teardown machinery behind each run.
+- [Generated configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-subagent-acp) — every accepted config field and its source declaration.
+
+-----
+
+<a id="model-experience"></a>
 ## Model Experience
 
 ### Child-agent request
 
 #### What the model sees
 
-The remote child receives the standalone task content through ACP plus its own process's configured system prompt, tools, and fresh session. It receives no parent conversation. This provider advertises no optional start-time capabilities, so the local service rejects requests for persona, tool filtering, depth enforcement, or structured output instead of silently omitting them.
+The remote child receives the standalone task content through ACP plus its own process's configured system prompt, tools, and fresh session. It receives no parent conversation. This provider advertises no optional start-time capabilities, so the local service rejects requests for `agentOptions`, persona, tool filtering, depth enforcement, or structured output instead of silently omitting them.
 
 #### Token effect
 
@@ -81,7 +139,7 @@ Independent of the parent request cache. Each ACP child can reuse only prefixes
 
 #### What the model sees
 
-Through `dsh-tool-subagent`, the parent receives only the child's final streamed assistant text or that consumer's exact stop-reason error, not intermediate messages or tool traffic. A request already cancelled before publication becomes exactly `Error: subagent request was aborted before the ACP child started`; other start failures pass through as `Error: <message>`.
+Through `dsh-tool-subagent`, the parent receives only the child's final streamed assistant text or that consumer's exact stop-reason error, not intermediate messages or tool traffic. Non-completed results present the safe diagnostic before separately preserved partial assistant output. A request already cancelled before publication becomes exactly `Error: subagent request was aborted before the ACP child started`; another start failure contains only the fixed `Subagent failure (...)` line.
 
 #### Token effect
 
@@ -93,8 +151,27 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 ## Known Limitations and Deferred Work
 
-- **A fresh process per run** — persistent-process pooling is a future optimization ([the seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.md)).
-- **Local workspaces only** — the resolved cwd is a local path handed to a child on the same machine; workspace mapping for a remote ACP agent would need its own backend capability and is not designed here.
-- **No optional start-time capabilities** — this provider cannot apply the local harness's `outputSchema`, depth cap, tool filter, or persona inside the remote process, so it advertises none and the service rejects requests that require them.
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define when this backend is a poor fit or needs special operational care. They are current package constraints, not a general ACP comparison or a task backlog.
+
+- **A fresh process per run** — there is no process pooling; each delegation pays the full spawn and ACP handshake cost.
+- **Local workspaces only** — the resolved working directory is a local path handed to a child on the same machine; remote workspace mapping is not designed.
+- **No optional start-time capabilities** — this provider cannot apply `agentOptions`, `outputSchema`, a depth cap, a tool filter, or a persona inside the remote process, so the seam rejects requests that require them.
 - **Only committed `agent_message_chunk` text is collected** — the automation server keeps reasoning, tool activity, plans, and other trace data in the child session log rather than emitting them on ACP.
 - **Permission prompts are auto-answered** (`permission: allow | reject`) — no human is surfaced a child's `session/request_permission`.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+This Dev Note is working context for maintainers: open questions and undecided directions. It is explicitly non-authoritative — shipped behavior and limits live in the sections above and in the package code.
+
+- **Process pooling** — persistent-process reuse is a possible future optimization but changes the per-run isolation model.
+- **Remote workspaces** — mapping a remote ACP agent's workspace would need its own backend capability.
+- **Continuable ACP children** — would require persisting the remote session id and a per-child continuation advertisement.
+
+</details>

package/README.zh.md

@@ -1,73 +1,131 @@
+---
+description: "面向用户与维护者的进程外 ACP subagent 后端，用于选择委派提供方、配置子 ACP agent 命令或排查远程子 agent 运行问题。"
+kind: "package-reference"
+---
+
 # @deepseek-ai/dsh-subagent-acp
 
 [English](README.md) | 中文
 
-ACP（Agent Client Protocol）提供方会在全新的子进程中运行每个 subagent，并作为 Agent Client Protocol 客户端驱动它。这是 spawn 与 fork 的进程外替代方案：子 agent（智能体）拥有自己的运行时、会话、模型配置和工具。
+## 概述
 
-## 启动与所有权
+`dsh-subagent-acp` 在全新的子进程中运行每个被委派的子 agent，并作为 Agent Client Protocol 客户端驱动它：子 agent（智能体）拥有自己的运行时、会话、模型配置和工具，可以是任何兼容 ACP 的 agent，而不只是 Harness。它是进程内 spawn 与 fork 后端的进程外替代方案，只与子 agent 共享父会话的工作目录。每次运行都会 spawn 全新进程、初始化 ACP 会话、发送任务并收集流式最终答案；权限提示由配置自动应答，因此无需人工参与。父级只收到子 agent 的最终答案或安全错误——中间消息与工具流量不会跨越边界。当子 agent 必须与父 harness 完全隔离且能说 ACP 时，选择它。
 
-`start(request)` 先解析子 agent 的工作目录，再依次执行 `spawn` → ACP `initialize` → `newSession`，然后才兑现。因此，兑现表示远程会话已就绪，所有权也已转移给调用方。spawn 失败、初始化失败、新建会话失败或因发布前取消而失败时，只有在子进程已回收后才会拒绝；工作目录解析失败则会在尚未 spawn 任何进程时拒绝。
+## 目录
 
-工作目录优先使用已配置的 `cwd` 覆盖值，否则使用执行委派的父会话 cwd，绝不使用服务器进程自身的 cwd，因为同一个服务器进程会服务来自多个工作区的会话。从父级取得的值必须是绝对路径，指向 harness 可以进入的目录（具备搜索权限，这是子进程 cwd 的要求）；解析后的同一路径同时作为子进程 cwd 和 ACP `session/new` 工作区。
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
 
-返回的运行 id 在父级命名空间中生成。子服务器的会话 id 只用于 ACP 协议调用，因为 ACP 只保证它在该全新子进程中唯一；若将其用作父级生命周期 id，可能与另一个远程运行或本地 agent 冲突。
+-----
 
-发布后，提供方发送提示词，并把流式 `agent_message_chunk` 文本收集到 `SubagentResult.output`。提示词/传输失败会以 `stopReason: 'error'` 兑现；如果必需的请求信号或 dispose（资源释放）请求了取消，则以 `aborted` 兑现。
+<a id="use-this-package"></a>
+## 使用本包
 
-`dispose()` 是幂等的。它会移除信号监听器，在可行时请求 ACP 取消，然后使用该 seam 定义的操作运行本后端自有的拆卸阶梯（`disposeAcpChild`）：先关闭 stdin 并等待 `disposeEofGraceMs` 让子进程协作式完全停稳，再触发句柄的 `terminate()` 升级（SIGTERM、spawn 宽限期、SIGKILL——Windows 直接强制终止），并等待子进程责任方给出整棵进程树的退出证明。每次运行都使用全新进程；尚未实现进程池。
+当组合需要一个说 Agent Client Protocol 的完全隔离进程外子 agent 时，挂载本提供方。常用路径是显式的：挂载 seam、挂载本提供方，并给出一个启动 ACP agent 的命令。
 
-## 能力与上下文
+### 何时选择
 
-ACP 不声明任何启动时能力，因为当前进程无法强制执行远程子 agent 的深度、工具过滤、persona 或结构化输出运行时。它也报告 `inheritsParentContext: false`：远程会话从全新状态开始，唯一源自父级的输入是上述工作区 cwd；对话上下文不会跨越进程边界。
+当子 agent 必须在独立进程中运行、拥有自己的运行时、模型和工具时选择此后端——例如来自其他项目的 ACP agent——或者你希望委派完全无法触及父 harness 时。当子 agent 必须共享父级组合或遵守父级强制的能力时，请选择进程内后端：本提供方不声明任何可选启动时能力，因此 seam 会拒绝要求 `agentOptions`、结构化输出、深度上限、工具过滤或 persona 的请求，而不是静默省略。
 
-## 配置
+### 配置
 
-| 键 | 默认值 | 含义 |
+| 字段 | 默认值 | 含义 |
 |---|---|---|
-| `providerName` | `acp` | `ctx.subagents` 上的注册表名称。 |
-| `command` | 必填 | 每次运行时 spawn 的可执行文件。 |
-| `args` | `[]` | 命令参数。 |
-| `cwd` | 父会话 cwd | 子进程及其 ACP 会话的工作目录覆盖值；不得为空。相对值会在加载时以 harness 启动目录为基准解析，结果必须指向 harness 可以进入的目录。 |
-| `permission` | `reject` | 自动回答权限请求：拒绝，或选择第一个 `allow_once` 或 `allow_always` 选项。 |
-| `env` | `{}` | 显式子进程环境，叠加到已清理凭据的父进程环境之上。 |
-| `disposeEofGraceMs` | `6000` | stdin EOF 之后、平台终止之前的宽限时间须为正值，且不得大于 [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.zh.md)。 |
-| `disposeGraceMs` | `3000` | POSIX 在 SIGTERM 后、SIGKILL 前的宽限时间（Windows 直接强制终止），须为正值且不得大于 [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.zh.md)。 |
+| `providerName` | `acp` | `ctx.subagents` 上的注册表名称 |
+| `command` | 必填 | 每次运行时 spawn 的可执行文件（子 ACP agent） |
+| `args` | `[]` | 命令参数 |
+| `cwd` | 父会话 cwd | 子进程及其 ACP 会话的工作目录覆盖值 |
+| `permission` | `reject` | 自动应答权限请求：拒绝，或选择第一个 `allow_once` 或 `allow_always` 选项（`allow`） |
+| `env` | `{}` | 叠加在已清理凭据的父环境之上的显式子环境 |
+| `disposeEofGraceMs` | `6000` | stdin EOF 之后、平台终止之前的宽限 |
+| `disposeGraceMs` | `3000` | 失败后观察结构化进程事实的时限；在 POSIX 上也是 SIGTERM 到 SIGKILL 的宽限 |
+
+生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-subagent-acp)是每个受支持字段及其 JSDoc 的穷尽式真源。
+
+DeepSeek Harness 子进程使用产品启动器和一个显式的绝对路径 `DSH_HOME`。隔离 home 可防止嵌套 runtime 发现启动者个人的 profile 或凭据；通用 ACP provider 不会把这一要求强加给非 DSH agent。
 
 ```yaml
 - id: subagent-acp
   name: '@deepseek-ai/dsh-subagent-acp'
   config:
     providerName: acp
-    command: node
-    args: ['--import', 'tsx', './packages/examples/acp-demo/src/bin.ts', '--config', './examples/acp-agent/cordis.yml']
+    command: dsh
+    args: ['--profile', 'acp', '--patch', '/absolute/path/to/acp.patch.yml']
     permission: reject
     env:
+      DSH_HOME: /absolute/path/to/isolated-child-home
       DEEPSEEK_API_KEY: !!js process.env.DEEPSEEK_API_KEY
 ```
 
-## 结束原因映射
+### 你会得到什么
+
+成功的运行会把子 agent 最终的流式 assistant 文本作为结果输出返回。子 agent 的会话、模型与工具来自子进程自身——父级只提供任务与工作目录。停止原因把 `end_turn` 映射为 `completed`、`max_tokens` 映射为 `max-tokens`、`refusal` 映射为 `refusal`、`cancelled` 映射为 `aborted`，其余值映射为 `error`。已发布运行失败时，部分 assistant 文本保留在 `output`，安全的结构化详情则单独放在 `diagnostic`。
+
+### 失败与恢复
+
+spawn、初始化或新建会话失败会在发布前拒绝，通常先等待子进程被回收。如果清理也失败，拒绝会保留有序、安全的启动与拆卸事实，但不会声称整棵进程树已经停稳。非取消错误只暴露固定的提供方、阶段与类别事实；原始失败保留在内部 cause 链与 Host 诊断中。发布后，提示词、传输或进程提前退出会以携带安全诊断的 `error` 结算；本地取消则以不带失败详情的 `aborted` 结算。
+
+### 安全诊断
+
+通用诊断使用固定的一行：`Subagent failure (provider: ACP; stage: <stage>; category: <category>; ...)`。可选的停止原因、退出码与信号只来自封闭协议或受管进程事实。stderr、异常文本、任务内容、工具输入、路径、环境值、凭据与协议载荷绝不会进入诊断；共享结果边界把诊断限制在 4096 个 UTF-8 字节内。请求过权限且未完成的运行可以增加一行固定的策略、工具种类与决定。成功运行和本地取消不包含该行。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节解释后端如何经 ACP 驱动子 agent，以及可观察行为从何而来；完整约定见[使用本包](#use-this-package)。
+
+### 设计理念
+
+- **完全进程隔离。** 每个子 agent 在全新子进程中运行，拥有自己的会话、模型与工具；只有解析后的工作目录从父级跨越。
+- **每次运行一个进程。** 每次运行都 spawn 新进程；没有进程池。
+- **ACP 协议格式（wire format）是序列化边界。** 同进程 subagent 值不会为防御目的克隆；协议才是校验不可信输入的地方。
+
+### 启动与所有权流程
 
-| ACP | Harness |
-|---|---|
-| `end_turn` | `completed` |
-| `max_tokens` | `max-tokens` |
-| `refusal` | `refusal` |
-| `cancelled` | `aborted` |
-| `max_turn_requests` 或未知值 | `error` |
+一次启动先解析子 agent 的工作目录（配置的 `cwd` 覆盖值，否则取父会话 cwd），经子进程 seam spawn 命令，完成 ACP `initialize` 与 `newSession` 握手，然后才发布运行。兑现意味着远程会话已就绪、所有权已转移给调用方。dispose（资源释放）是幂等的：先关闭 stdin 并按配置的宽限等待协作式完全停稳，再经 SIGTERM 升级到 SIGKILL，并等待整棵进程树退出。清理失败会作为有序的安全事实保持可观察，且绝不声称已经完全停稳。
 
-## 进程边界
+### 停止原因映射
 
-子进程经由 [`dsh-subprocess`](../../subprocess/subprocess/README.zh.md) seam spawn：共享的凭据清除先移除疑似凭据的环境变量和环境中已有的 `DSH_*` 名称，显式 `config.env` 值在清除之后合并（有意转发的 `DEEPSEEK_API_KEY` 会保留下来，`DSH_PERMISSION_MODE` 这类 `DSH_*` 部署事实也以同样的方式到达子进程——清除只丢弃其陈旧的同名环境值），stderr 会继承到父进程自身的流，dispose 则先应用本插件的 EOF 时间窗，再由子进程责任方执行 SIGTERM→SIGKILL 升级并等待整棵进程树退出。ACP 协议格式（wire format）是真正的序列化边界；同进程 subagent 值不会为防御目的而克隆。
+运行结果会把 ACP 终态映射进共享的停止原因词汇（`completed`、`max-tokens`、`refusal`、`aborted` 或 `error`），实现见 [`src/run.ts`](src/run.ts)。
 
-本包没有默认导出。否则 Cordis loader 的解包会隐藏具名 `inject` 元数据；见[事故复盘（postmortem）0001](../../../docs/postmortem/0001-acp-default-export-drops-inject.zh.md)。
+### 进程边界
 
+子进程经子进程 seam spawn：先清除疑似凭据的环境变量，再合并显式 `config.env` 值。stderr 继承到父级流，dispose 先应用本提供方的 EOF 窗口，再执行共享的逐级终止。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当包级约定不够用时阅读以下页面。它们从本后端逐步进入它接入的 seam 与它驱动的协议。
+
+- [Subagent 子系统](../../../docs/subsystems/subagent.zh.md)——服务约定、提供方约定与终态结果语义。
+- [dsh-subagent seam](../subagent/README.zh.md)——本提供方注册于其上的注册表与启动 API。
+- [Agent Client Protocol 自动化服务器](../../acp/acp/README.zh.md)——本提供方作为客户端驱动的仅自动化服务器。
+- [dsh-subprocess seam](../../subprocess/subprocess/README.zh.md)——每次运行背后的进程 spawn 与清理机制。
+- [生成配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-subagent-acp)——每个受支持配置字段及其源声明。
+
+-----
+
+<a id="model-experience"></a>
 ## 模型体验
 
 ### 子 agent 请求
 
-#### 模型看到的内容
+#### 模型看到什么
 
-远程子 agent 通过 ACP 接收独立任务内容，并使用其自身进程配置的系统提示词、工具和全新会话。它不接收父级对话。该提供方不声明任何可选启动时能力，因此本地服务会拒绝要求 persona、工具过滤、深度强制或结构化输出的请求，而不是静默省略这些要求。
+远程子 agent 通过 ACP 接收独立任务内容，并使用其自身进程配置的系统提示词、工具和全新会话。它不接收父级对话。本提供方不声明可选启动时能力，因此本地服务会拒绝要求 `agentOptions`、persona、工具过滤、深度强制或结构化输出的请求，而不是静默省略。
 
 #### Token 影响
 
@@ -79,22 +137,41 @@ ACP 不声明任何启动时能力，因为当前进程无法强制执行远程
 
 ### 父级工具结果（间接）
 
-#### 模型看到的内容
+#### 模型看到什么
 
-通过 `dsh-tool-subagent`，父级只接收子 agent 最终的流式 assistant 文本，或该消费方给出的精确结束原因错误；不接收中间消息或工具流量。发布前已经取消的请求会精确变为 `Error: subagent request was aborted before the ACP child started`；其他启动失败按原样传递为 `Error: <message>`。
+通过 `dsh-tool-subagent`，父级只接收子 agent 最终的流式 assistant 文本或该消费方给出的精确停止原因错误，不接收中间消息或工具流量。未完成的结果会先呈现安全诊断，再单独保留部分 assistant 输出。发布前已经取消的请求会精确变为 `Error: subagent request was aborted before the ACP child started`；其他启动失败只包含固定的 `Subagent failure (...)` 行。
 
 #### Token 影响
 
-父级输入只增加最终结果或错误，其内容依赖数据，并保留到压缩（compaction）为止。该提供方自身不会添加父级 schema。
+父级输入只增加最终结果或错误，其内容依赖数据，并保留到压缩（compaction）为止。本提供方自身不会添加父级 schema。
 
 #### KV Cache 影响
 
 仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。
 
-## 已知限制与暂缓事项
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明本后端何时不合适，或何时需要特别的运维注意。它们是当前包约束，不是通用 ACP 对比或任务积压。
+
+- **每次运行使用全新进程**——没有进程池；每次委派都要付出完整的 spawn 与 ACP 握手成本。
+- **仅支持本地工作区**——解析后的工作目录是交给同一台机器上子进程的本地路径；远程工作区映射尚未设计。
+- **不支持可选启动时能力**——本提供方无法在远程进程内应用 `agentOptions`、`outputSchema`、深度上限、工具过滤器或 persona，因此 seam 会拒绝需要它们的请求。
+- **只收集已提交的 `agent_message_chunk` 文本**——自动化服务器把推理（reasoning）、工具活动、计划和其他 trace 数据保留在子 agent 会话日志中，不通过 ACP 发出。
+- **权限提示自动应答**（`permission: allow | reject`）——不会把子 agent 的 `session/request_permission` 呈现给人。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+本开发备注是维护者的工作上下文：开放问题与尚未决定的探索方向。它明确不具权威性——已交付的行为与限制以上文和包代码为准。
+
+- **进程池**——持久进程复用是可能的未来优化，但会改变每次运行的隔离模型。
+- **远程工作区**——映射远程 ACP agent 的工作区需要独立的后端能力。
+- **可继续 ACP 子级**——需要持久化远程会话 id 与逐子级的继续执行能力声明。
 
-- **每次运行使用全新进程**：持久进程池属于后续优化（见 [seam Agent Note](../../../.agents/notes/implemented/feature/2026-06-21-subagent-capability-seam.zh.md)）。
-- **仅支持本地工作区**：解析后的 cwd 是交给同一台机器上子进程的本地路径；远程 ACP agent 的工作区映射需要独立的后端能力，此处尚未设计这种能力。
-- **不支持可选启动时能力**：该提供方无法在远程进程内应用本地 harness 的 `outputSchema`、深度上限、工具过滤器或 persona，因此不会声明这些能力；服务会拒绝需要它们的请求。
-- **只收集已提交的 `agent_message_chunk` 文本**：自动化服务器把推理（reasoning）、工具活动、计划和其他 trace 数据保留在子 agent 会话日志中，不通过 ACP 发出。
-- **权限提示自动回答**（`permission: allow | reject`）：不会把子 agent 的 `session/request_permission` 呈现给人。
+</details>

package/lib/index.js

@@ -4,23 +4,76 @@ import z from "@deepseek-ai/schemastery";
 import { MAX_TIMER_DELAY_MS } from "@deepseek-ai/dsh-timeout";
 import { randomUUID } from "node:crypto";
 import { Readable, Writable } from "node:stream";
-import { ClientSideConnection, PROTOCOL_VERSION, ndJsonStream } from "@agentclientprotocol/sdk";
-import { SessionId } from "@deepseek-ai/dsh-session";
-import { AssistantOutputFold } from "@deepseek-ai/dsh-subagent";
+import { PROTOCOL_VERSION, client, methods, ndJsonStream } from "@agentclientprotocol/sdk";
+import { brandString } from "@deepseek-ai/dsh-brand";
+import { AssistantOutputFold, settleRunResult, subprocessRunHandle } from "@deepseek-ai/dsh-subagent";
 //#region lib/types/run.js
 /**
 * Fresh-process ACP subagent client. Drives one child session and owns cancellation and
 * quiescent disposal.
 *
-* TODO(acp-subagent-replay): add snapshot-tier coverage with a separate replay fixture and
-* sessions root inside each child process. Current keyless coverage uses a scripted ACP child;
-* with-key coverage drives the real ACP example.
 * @module @deepseek-ai/dsh-subagent-acp/run
 */
 /** EOF grace for child flush and nested-process teardown; wider than the signal grace below. */
 const DEFAULT_DISPOSE_EOF_GRACE_MS = 6e3;
 /** Default POSIX grace between SIGTERM and SIGKILL on dispose (the `disposeGraceMs` config). */
 const DEFAULT_DISPOSE_GRACE_MS = 3e3;
+const ACP_TOOL_KINDS = new Set([
+	"read",
+	"edit",
+	"delete",
+	"move",
+	"search",
+	"execute",
+	"think",
+	"fetch",
+	"switch_mode",
+	"other"
+]);
+/** Fixed safe failure text derived only from provider-owned structured facts. */
+function failureDiagnostic(facts) {
+	const fields = [
+		"provider: ACP",
+		`stage: ${facts.stage}`,
+		`category: ${facts.category}`
+	];
+	if (facts.stopReason !== void 0) fields.push(`stop reason: ${facts.stopReason}`);
+	if (facts.outcome?.exitCode !== null && facts.outcome?.exitCode !== void 0) fields.push(`exit code: ${facts.outcome.exitCode}`);
+	/* v8 ignore next -- Windows does not report POSIX child signals in SubprocessOutcome. */
+	if (facts.outcome?.signal !== null && facts.outcome?.signal !== void 0) fields.push(`signal: ${facts.outcome.signal}`);
+	return `Subagent failure (${fields.join("; ")})`;
+}
+/** Fixed permission fact; ACP tool titles and option text never enter it. */
+function permissionDiagnostic(permission) {
+	return `ACP unattended decision (policy: ${permission.policy}; request: ${permission.request}; decision: ${permission.decision})`;
+}
+/** Put the operation failure first, followed by the latest permission decision. */
+function diagnosticText(facts, permission) {
+	const failure = failureDiagnostic(facts);
+	return permission === void 0 ? failure : `${failure}\n${permissionDiagnostic(permission)}`;
+}
+var AcpRunFailure = class extends Error {
+	constructor(facts, cause) {
+		super(`subagent-acp: ${failureDiagnostic(facts)}`, { cause });
+		this.name = "AcpRunFailure";
+	}
+};
+/**
+* Hide a pre-spawn workspace/configuration failure behind fixed safe facts.
+* @param cause - original Host failure retained on the Error cause chain.
+* @returns an Error whose message contains only the fixed ACP failure line.
+*/
+function acpConfigurationFailure(cause) {
+	return new AcpRunFailure({
+		stage: "initialize",
+		category: "configuration"
+	}, cause);
+}
+/** Keep only the closed ACP tool-kind vocabulary; future values use a fixed fallback. */
+function permissionRequestKind(kind) {
+	const candidate = kind ?? "unknown";
+	return ACP_TOOL_KINDS.has(candidate) ? candidate : "unknown";
+}
 /** Bounded whole-tree exit wait: polls the handle's tree liveness until it exits or `ms` elapses. */
 async function treeExitsWithin(child, ms) {
 	const controller = new AbortController();
@@ -94,10 +147,57 @@ function toError(value) {
 	/* v8 ignore next */
 	return value instanceof Error ? value : new Error(String(value));
 }
+/** Report an original Host failure without letting the observation sink replace it. */
+function reportFailure(spec, error) {
+	try {
+		spec.onError?.(toError(error), "error");
+	} catch {}
+}
+/** Classify an unpublished failure from the active protocol operation and observed process facts. */
+function startupFailure(error, stage, child, outcome) {
+	if (child.pid <= 0) return new AcpRunFailure({
+		stage: "process",
+		category: "process-start"
+	}, error);
+	return new AcpRunFailure(
+		/* v8 ignore next -- Windows anonymous pipes cannot expose a live-child protocol close during startup. */
+		outcome === void 0 ? {
+			stage,
+			category: "transport"
+		} : {
+			stage,
+			category: "process-exit",
+			outcome
+		},
+		error
+	);
+}
+/** Map one remote terminal reason to the optional safe failure line it needs. */
+function terminalFailure(reason, permission) {
+	switch (reason) {
+		case "end_turn": return;
+		case "max_turn_requests": return diagnosticText({
+			stage: "prompt",
+			category: "remote-limit",
+			stopReason: "max_turn_requests"
+		}, permission);
+		case "max_tokens":
+		case "refusal":
+		case "cancelled": return permission === void 0 ? void 0 : permissionDiagnostic(permission);
+		default: return diagnosticText({
+			stage: "prompt",
+			category: "unknown",
+			stopReason: "unknown"
+		}, permission);
+	}
+}
 /**
 * Start and publish one ACP child after initialization and session creation.
-* Child failures resolve through the run result; startup failures reject after
-* process reap. Disposal cancels, kills, and reaps the child.
+* Child failures resolve through the run result. Startup rejects with fixed
+* safe facts after provider-owned cleanup; successful cleanup proves process
+* reap. Cleanup failure preserves startup plus teardown facts for an ordinary
+* failure, or teardown alone after cancellation, without claiming quiescence.
+* Disposal cancels, kills, and reaps the child.
 * @param request - the start request; its signal is the cancellation channel.
 * @param spec - the resolved spawn spec: command/args/cwd, env, permission
 * policy, dispose graces, and the optional error sink.
@@ -105,50 +205,95 @@ function toError(value) {
 */
 async function startAcpRun(request, spec) {
 	if (request.signal.aborted) throw new Error("subagent request was aborted before the ACP child started");
-	const id = SessionId(randomUUID());
-	const child = spec.spawn({
-		argv: [spec.command, ...spec.args],
-		cwd: spec.cwd,
-		stdio: {
-			stdin: "pipe",
-			stdout: "pipe",
-			stderr: "inherit"
-		},
-		graceMs: spec.disposeGraceMs,
-		env: spec.env
-	});
+	const id = brandString(randomUUID());
+	let child;
+	try {
+		child = spec.spawn({
+			argv: [spec.command, ...spec.args],
+			cwd: spec.cwd,
+			stdio: {
+				stdin: "pipe",
+				stdout: "pipe",
+				stderr: "inherit"
+			},
+			graceMs: spec.disposeGraceMs,
+			env: spec.env
+		});
+	} catch (error) {
+		reportFailure(spec, error);
+		throw new AcpRunFailure({
+			stage: "process",
+			category: "process-start"
+		}, error);
+	}
 	/* v8 ignore start -- 'pipe' dispositions expose both streams by the seam contract; defensive. */
 	if (child.stdin === void 0 || child.stdout === void 0) throw new Error("subagent-acp: subprocess implementation dropped a piped protocol stream");
 	/* v8 ignore stop */
-	const spawnFailed = child.done.then(
+	let processOutcome;
+	const processDone = child.done.then((outcome) => {
+		processOutcome = outcome;
+		return outcome;
+	});
+	const spawnFailed = processDone.then(
 		/* v8 ignore next -- the success arm's never-settling executor is intentionally empty. */
 		() => new Promise(() => {}),
 		(err) => Promise.reject(toError(err))
 	);
 	spawnFailed.catch(() => {});
+	const observeProcessOutcome = async (signal) => {
+		if (processOutcome !== void 0 || child.pid <= 0) return processOutcome;
+		const timeout = AbortSignal.timeout(Math.ceil(spec.disposeGraceMs));
+		const bound = signal === void 0 ? timeout : AbortSignal.any([signal, timeout]);
+		const aborted = Promise.withResolvers();
+		/* v8 ignore next -- Windows cannot expose the live-child protocol close needed to await this abort. */
+		const onObservationAbort = () => {
+			aborted.resolve(void 0);
+		};
+		bound.addEventListener("abort", onObservationAbort, { once: true });
+		/* v8 ignore next -- closes the event-loop race between listener registration and the preceding derived-signal check. */
+		if (bound.aborted) onObservationAbort();
+		try {
+			return await Promise.race([processDone, aborted.promise]);
+		} catch {
+			/* v8 ignore next -- a published child.done cannot reject; spawn rejection is consumed before publication. */
+			return processOutcome;
+		} finally {
+			bound.removeEventListener("abort", onObservationAbort);
+		}
+	};
 	let processDisposal;
 	const disposeProcess = () => processDisposal ??= disposeAcpChild(child, spec.disposeEofGraceMs);
 	const fold = new AssistantOutputFold();
 	const flags = { cancelled: false };
-	const makeClient = (_agent) => ({
-		sessionUpdate(params) {
-			const update = params.update;
-			if (update.sessionUpdate === "agent_message_chunk") fold.pushText(acpContentText(update.content));
-			return Promise.resolve();
-		},
-		requestPermission(params) {
-			if (spec.permission === "allow") {
-				const allow = params.options.find((o) => o.kind === "allow_once" || o.kind === "allow_always");
-				if (allow !== void 0) return Promise.resolve({ outcome: {
+	let latestPermission;
+	const agent = client({ name: "deepseek-harness-subagent-acp" }).onNotification(methods.client.session.update, ({ params }) => {
+		const update = params.update;
+		if (update.sessionUpdate === "agent_message_chunk") fold.pushText(acpContentText(update.content));
+		return Promise.resolve();
+	}).onRequest(methods.client.session.requestPermission, ({ params }) => {
+		if (spec.permission === "allow") {
+			const allow = params.options.find((o) => o.kind === "allow_once" || o.kind === "allow_always");
+			if (allow !== void 0) {
+				latestPermission = {
+					policy: "allow",
+					request: permissionRequestKind(params.toolCall.kind),
+					decision: "allowed"
+				};
+				return Promise.resolve({ outcome: {
 					outcome: "selected",
 					optionId: allow.optionId
 				} });
 			}
-			return Promise.resolve({ outcome: { outcome: "cancelled" } });
 		}
-	});
-	const conn = new ClientSideConnection(makeClient, ndJsonStream(Writable.toWeb(child.stdin), Readable.toWeb(child.stdout)));
+		latestPermission = {
+			policy: spec.permission,
+			request: permissionRequestKind(params.toolCall.kind),
+			decision: "denied"
+		};
+		return Promise.resolve({ outcome: { outcome: "cancelled" } });
+	}).connect(ndJsonStream(Writable.toWeb(child.stdin), Readable.toWeb(child.stdout))).agent;
 	let sessionId;
+	let startupStage = "initialize";
 	let signalCancelSettled;
 	const cancelSettled = new Promise((resolve) => {
 		signalCancelSettled = resolve;
@@ -158,7 +303,7 @@ async function startAcpRun(request, spec) {
 		flags.cancelled = true;
 		signalCancelSettled();
 		/* v8 ignore next */
-		if (sessionId !== void 0) conn.cancel({ sessionId }).catch(() => {});
+		if (sessionId !== void 0) agent.notify(methods.agent.session.cancel, { sessionId }).catch(() => {});
 	};
 	const onAbort = () => {
 		requestCancel();
@@ -168,17 +313,22 @@ async function startAcpRun(request, spec) {
 	try {
 		await Promise.race([
 			(async () => {
-				await conn.initialize({
+				await agent.request(methods.agent.initialize, {
 					protocolVersion: PROTOCOL_VERSION,
 					clientCapabilities: {}
 				});
-				const session = await conn.newSession({
+				startupStage = "new-session";
+				const session = await agent.request(methods.agent.session.new, {
 					cwd: spec.cwd,
 					mcpServers: []
 				});
 				const returnedSessionId = Reflect.get(session, "sessionId");
-				if (typeof returnedSessionId !== "string") throw new Error("ACP child published without a session id");
+				if (typeof returnedSessionId !== "string") throw new AcpRunFailure({
+					stage: "new-session",
+					category: "protocol"
+				}, /* @__PURE__ */ new Error("ACP child published without a session id"));
 				sessionId = returnedSessionId;
+				/* v8 ignore next -- cancelSettled wins the startup race before this post-response guard can settle it. */
 				if (flags.cancelled) throw new Error("subagent cancelled before the ACP session started");
 			})(),
 			spawnFailed,
@@ -188,59 +338,86 @@ async function startAcpRun(request, spec) {
 		]);
 	} catch (error) {
 		request.signal.removeEventListener("abort", onAbort);
-		await disposeProcess();
-		if (flags.cancelled) throw new Error("subagent request was aborted before the ACP child started");
-		throw toError(error);
+		const startup = flags.cancelled ? { kind: "cancelled" } : {
+			kind: "failed",
+			failure: error instanceof AcpRunFailure ? error : startupFailure(error, startupStage, child, await observeProcessOutcome())
+		};
+		if (startup.kind === "cancelled") {} else reportFailure(spec, error instanceof AcpRunFailure ? error.cause : error);
+		try {
+			await disposeProcess();
+		} catch (cleanupError) {
+			reportFailure(spec, cleanupError);
+			const cleanupFailure = new AcpRunFailure({
+				stage: "teardown",
+				category: processOutcome === void 0 ? "unknown" : "process-exit",
+				...processOutcome === void 0 ? {} : { outcome: processOutcome }
+			}, cleanupError);
+			if (startup.kind === "cancelled") throw new AggregateError([cleanupFailure], cleanupFailure.message);
+			throw new AggregateError([startup.failure, cleanupFailure], `${startup.failure.message}; ${cleanupFailure.message}`);
+		}
+		if (startup.kind === "cancelled") throw new Error("subagent request was aborted before the ACP child started");
+		throw startup.failure;
 	}
 	/* v8 ignore next */
 	if (sessionId === void 0) throw new Error("unreachable: ACP startup fulfilled without a session id");
 	const remoteSessionId = sessionId;
-	const result = (async () => {
-		try {
-			const prompt = async () => {
-				const promptResult = await conn.prompt({
-					sessionId: remoteSessionId,
-					prompt: toAcpPrompt(request.prompt)
-				});
-				return {
-					output: collectOutput(),
-					stopReason: acpStopReason(promptResult.stopReason)
-				};
-			};
-			return await Promise.race([prompt(), cancelSettled.then(() => ({
-				output: collectOutput(),
-				stopReason: "aborted"
-			}))]);
-		} catch (error) {
-			/* v8 ignore next */
-			if (flags.cancelled) return {
-				output: collectOutput(),
-				stopReason: "aborted"
-			};
-			try {
-				spec.onError?.(toError(error), "error");
-			} catch {}
-			return {
-				output: collectOutput(),
-				stopReason: "error"
-			};
-		} finally {
-			request.signal.removeEventListener("abort", onAbort);
-		}
-	})();
-	let disposal;
-	return {
+	let diagnostic;
+	return subprocessRunHandle({
 		id,
-		localAgent: void 0,
-		result,
-		dispose() {
-			if (disposal !== void 0) return disposal;
-			request.signal.removeEventListener("abort", onAbort);
-			requestCancel();
-			disposal = disposeProcess();
-			return disposal;
+		result: settleRunResult({
+			attempt: async () => {
+				try {
+					const promptResult = await Promise.race([agent.request(methods.agent.session.prompt, {
+						sessionId: remoteSessionId,
+						prompt: toAcpPrompt(request.prompt)
+					}), cancelSettled.then(() => {
+						throw new Error("subagent cancelled while the ACP prompt was running");
+					})]);
+					const stopReason = acpStopReason(promptResult.stopReason);
+					diagnostic = terminalFailure(promptResult.stopReason, latestPermission);
+					return {
+						output: collectOutput(),
+						...diagnostic === void 0 ? {} : { diagnostic },
+						stopReason
+					};
+				} catch (error) {
+					if (!flags.cancelled) {
+						const outcome = await observeProcessOutcome(request.signal);
+						diagnostic = diagnosticText(outcome === void 0 ? {
+							stage: "prompt",
+							category: "transport"
+						} : {
+							stage: "process",
+							category: "process-exit",
+							outcome
+						}, latestPermission);
+					}
+					throw error;
+				}
+			},
+			collectOutput,
+			collectDiagnostic: () => diagnostic,
+			cancelled: () => flags.cancelled,
+			onError: spec.onError,
+			signal: request.signal,
+			onAbort
+		}),
+		signal: request.signal,
+		onAbort,
+		requestCancel,
+		teardown: async () => {
+			try {
+				await disposeProcess();
+			} catch (error) {
+				reportFailure(spec, error);
+				throw new AcpRunFailure({
+					stage: "teardown",
+					category: processOutcome === void 0 ? "unknown" : "process-exit",
+					...processOutcome === void 0 ? {} : { outcome: processOutcome }
+				}, error);
+			}
 		}
-	};
+	});
 }
 //#endregion
 //#region lib/types/index.js
@@ -264,7 +441,7 @@ const Config = z.object({
 	disposeEofGraceMs: z.number().default(DEFAULT_DISPOSE_EOF_GRACE_MS),
 	disposeGraceMs: z.number().default(DEFAULT_DISPOSE_GRACE_MS)
 });
-/** A dispose grace must fit the single Node timer that owns its teardown tier. */
+/** A process grace must fit every Node timer that observes or terminates the child. */
 function assertPositiveFinite(name, value) {
 	if (!Number.isFinite(value) || value <= 0 || value > MAX_TIMER_DELAY_MS) throw new Error(`subagent-acp: ${name} must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`);
 }
@@ -312,14 +489,15 @@ function resolveCwd(configured, request) {
 }
 /**
 * The ACP provider. Advertises NO start-time capabilities: an out-of-process
-* child cannot honor `outputSchema`/`maxDepth`/`toolFilter` (the service rejects
-* a request needing any of them before `start` runs).
+* child cannot honor `agentOptions`/`outputSchema`/`maxDepth`/`toolFilter`/
+* `persona` (the service rejects a request needing any before `start` runs).
 */
 var AcpProvider = class {
 	name;
 	ctx;
 	config;
 	capabilities = {
+		agentOptions: false,
 		outputSchema: false,
 		depthLimit: false,
 		toolFilter: false,
@@ -332,10 +510,19 @@ var AcpProvider = class {
 		this.config = config;
 	}
 	start(request) {
+		if (request.signal.aborted) throw new Error("subagent request was aborted before the ACP child started");
+		let cwd;
+		try {
+			cwd = resolveCwd(this.config.cwd, request);
+		} catch (error) {
+			const failure = acpConfigurationFailure(error);
+			this.ctx.logger.warn(`subagent-acp "${this.name}": child start failed: %o`, error);
+			throw failure;
+		}
 		return startAcpRun(request, {
 			command: this.config.command,
 			args: this.config.args,
-			cwd: resolveCwd(this.config.cwd, request),
+			cwd,
 			permission: this.config.permission,
 			env: this.config.env,
 			disposeEofGraceMs: this.config.disposeEofGraceMs,

package/lib/types/index.d.ts

@@ -47,7 +47,7 @@ export interface Config {
      * `MAX_TIMER_DELAY_MS`.
      */
     disposeEofGraceMs?: number;
-    /** Termination-escalation grace (ms); must not exceed `MAX_TIMER_DELAY_MS`. */
+    /** Failure-observation and termination-escalation grace (ms); must not exceed `MAX_TIMER_DELAY_MS`. */
     disposeGraceMs?: number;
 }
 export declare const Config: z<Config>;

package/lib/types/run.d.ts

@@ -2,9 +2,6 @@
  * Fresh-process ACP subagent client. Drives one child session and owns cancellation and
  * quiescent disposal.
  *
- * TODO(acp-subagent-replay): add snapshot-tier coverage with a separate replay fixture and
- * sessions root inside each child process. Current keyless coverage uses a scripted ACP child;
- * with-key coverage drives the real ACP example.
  * @module @deepseek-ai/dsh-subagent-acp/run
  */
 import { type ContentBlock as AcpContentBlock, type StopReason } from '@agentclientprotocol/sdk';
@@ -45,9 +42,11 @@ export interface AcpRunSpec {
      */
     disposeEofGraceMs: number;
     /**
-     * Termination-escalation grace (ms) in {@link SubagentRun.dispose}; POSIX
-     * waits this long after `SIGTERM` before `SIGKILL`, while Windows
-     * force-terminates directly. The plugin fills it from `disposeGraceMs`.
+     * Process-observation and termination-escalation grace (ms). Failure
+     * classification waits at most this long for structured exit facts; POSIX
+     * dispose also waits this long after `SIGTERM` before `SIGKILL`, while
+     * Windows force-terminates directly. The plugin fills it from
+     * `disposeGraceMs`.
      */
     disposeGraceMs: number;
     /**
@@ -57,12 +56,9 @@ export interface AcpRunSpec {
      */
     spawn: (spec: SubprocessSpawnSpec) => SubprocessHandle;
     /**
-     * Sink for a child-level failure that the run flattened into a stop reason
-     * (the seam contract forbids `result` rejecting). The driver calls this with
-     * the original error and the chosen stop reason so the fault is preserved
-     * rather than silently lost; the provider wires it to `ctx.logger.warn`.
-     * A throw from the sink itself is contained — it cannot reject `result`.
-     * Optional — omitted in a unit test that asserts the stop reason directly.
+     * Host sink for startup, published-run, or teardown failures. Model-visible
+     * text uses fixed safe facts, while this callback retains the original Error
+     * when one exists. A throw from the sink itself is contained.
      */
     onError?: (error: Error, stopReason: SubagentStopReason) => void;
 }
@@ -70,6 +66,12 @@ export interface AcpRunSpec {
 export declare const DEFAULT_DISPOSE_EOF_GRACE_MS = 6000;
 /** Default POSIX grace between SIGTERM and SIGKILL on dispose (the `disposeGraceMs` config). */
 export declare const DEFAULT_DISPOSE_GRACE_MS = 3000;
+/**
+ * Hide a pre-spawn workspace/configuration failure behind fixed safe facts.
+ * @param cause - original Host failure retained on the Error cause chain.
+ * @returns an Error whose message contains only the fixed ACP failure line.
+ */
+export declare function acpConfigurationFailure(cause: unknown): Error;
 /**
  * Cooperative teardown ladder for an out-of-process agent, over the seam's
  * public verbs; resolves only at whole-tree quiescence: stdin EOF (the child's
@@ -101,8 +103,11 @@ export declare function acpContentText(content: AcpContentBlock): string;
 export declare function toAcpPrompt(prompt: ContentBlock[]): AcpContentBlock[];
 /**
  * Start and publish one ACP child after initialization and session creation.
- * Child failures resolve through the run result; startup failures reject after
- * process reap. Disposal cancels, kills, and reaps the child.
+ * Child failures resolve through the run result. Startup rejects with fixed
+ * safe facts after provider-owned cleanup; successful cleanup proves process
+ * reap. Cleanup failure preserves startup plus teardown facts for an ordinary
+ * failure, or teardown alone after cancellation, without claiming quiescence.
+ * Disposal cancels, kills, and reaps the child.
  * @param request - the start request; its signal is the cancellation channel.
  * @param spec - the resolved spawn spec: command/args/cwd, env, permission
  * policy, dispose graces, and the optional error sink.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-subagent-acp",
   "description": "Out-of-process ACP subagent backend: drives a child agent in a spawned subprocess over the Agent Client Protocol",
-  "version": "0.1.1-rc.2",
+  "version": "0.1.2-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -32,30 +32,37 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-agent": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-session": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-subagent": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-subprocess": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-timeout": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-agent": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-subagent": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-subprocess": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-timeout": "^0.1.2-alpha.2"
   },
   "dependencies": {
-    "@agentclientprotocol/sdk": "0.25.1",
-    "@deepseek-ai/schemastery": "^3.18.1"
+    "@agentclientprotocol/sdk": "1.4.0",
+    "@deepseek-ai/dsh-brand": "^0.1.2-alpha.2",
+    "@deepseek-ai/schemastery": "^3.18.2"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis-plugin-loader": "^1.0.2",
-    "@deepseek-ai/dsh-agent": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-loader-smoke": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-session": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-subagent": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-subprocess": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-subprocess-local": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-timeout": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
+    "@deepseek-ai/dsh-agent": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-agent-spine-demo": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-app-boot": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-loader-smoke": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session-checkpoint-policy": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session-projection": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-subagent": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-subprocess": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-subprocess-local": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-timeout": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-tool-subagent": "^0.1.2-alpha.2"
   }
 }