Merge latest master into Codex subagent provider

2026-08-06 21:26:31 +08:00
parent 9e91e206d4 6a32047e77
commit 0748ebee39
2612 changed files with 56217 additions and 27538 deletions
--- a/packages/README.i18n.yaml
+++ b/packages/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/README.md
-README.md: 4832fffbc8963b8a7b1f8332e691083195bf94bc
-README.zh.md: 076b4f877070fcf0ee6b98d2310d1121cbbe63d6
+README.md: dec4d71ca2d323fe05f918dd3bf4709cfa01878e
+README.zh.md: 9596dfe8bf8d2d6144ffe7820886342707dd3009
--- a/packages/README.md
+++ b/packages/README.md
@@ -31,9 +31,10 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 | [`spill/`](spill/README.md) | Spill capability family: storage seam, local impl, tool-result spill policy | Product — stable surface |
 | [`todo/`](todo/README.md) | The model-facing `todo_write` tool | Product — stable surface |
 | [`plan/`](plan/README.md) | Plan collaboration state with a direct entry command and reviewed exit | Product — stable surface |
-| [`timeout/`](timeout/README.md) | Tool-call timeout policy: the `tools/execute` deadline enforcer | Product — stable surface |
-| [`guard/`](guard/README.md) | Loop-hygiene guards: advisory repeat-call reminders | Product — stable surface |
-| [`cordis/`](cordis/README.md) | Cordis runtime integration: self-inspection/model-written temporary Plugins and restricted repository Plugin loading | Product — stable surface |
+| [`timeout/`](timeout/README.md) | Tool-call `tools/execute` deadline enforcement | Product — stable surface |
+| [`guard/`](guard/README.md) | Loop-hygiene advisory repeat-call reminders | Product — stable surface |
+| [`bundle/`](bundle/README.md) | Installable `dsh --profile` patch layers | Product — stable surface |
+| [`cordis/`](cordis/README.md) | Cordis runtime integration: self-inspection, temporary Plugins, restricted repository Plugin loading | Product — stable surface |
 | [`hooks/`](hooks/README.md) | Hook bridges + the shared Claude Code / Codex wire-protocol library | Product — stable surface |
 | [`session-persistence/`](session-persistence/README.md) | Persistence seam + JSONL/SQLite backends | Product — stable surface |
 | [`session-projection/`](session-projection/README.md) | Projection seam: domain fold units serve whole values | Product — stable surface |
--- a/packages/README.zh.md
+++ b/packages/README.zh.md
@@ -31,9 +31,10 @@
 | [`spill/`](spill/README.md) | 溢出能力系列：存储 seam、本地实现、工具结果溢出策略 | 产品：稳定表面 |
 | [`todo/`](todo/README.md) | 面向模型的 `todo_write` 工具 | 产品：稳定表面 |
 | [`plan/`](plan/README.md) | Plan 协作状态，提供直接进入命令与经评审的退出 | 产品：稳定表面 |
-| [`timeout/`](timeout/README.md) | 工具调用超时策略：`tools/execute` 截止时间强制执行器 | 产品：稳定表面 |
-| [`guard/`](guard/README.md) | 循环卫生守卫：建议性重复调用提醒 | 产品：稳定表面 |
-| [`cordis/`](cordis/README.md) | Cordis 运行时集成：自检／模型编写的临时 Plugin，以及受限 repository Plugin 加载 | 产品：稳定表面 |
+| [`timeout/`](timeout/README.md) | 工具调用 `tools/execute` 截止时间强制执行 | 产品：稳定表面 |
+| [`guard/`](guard/README.md) | 循环卫生建议性重复调用提醒 | 产品：稳定表面 |
+| [`bundle/`](bundle/README.md) | 可安装的 `dsh --profile` 补丁层 | 产品：稳定表面 |
+| [`cordis/`](cordis/README.md) | Cordis 运行时集成：自检、临时 Plugin、受限 repository Plugin 加载 | 产品：稳定表面 |
 | [`hooks/`](hooks/README.md) | 钩子桥接 + 共享 Claude Code／Codex 协议格式库 | 产品：稳定表面 |
 | [`session-persistence/`](session-persistence/README.md) | 持久化 seam + JSONL/SQLite 后端 | 产品：稳定表面 |
 | [`session-projection/`](session-projection/README.md) | 投影 seam：领域折叠单元供给全量值 | 产品：稳定表面 |
--- a/packages/acp/README.i18n.yaml
+++ b/packages/acp/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/acp/README.md
-README.md: 326615210e5cfc39004fc5ab7462623089ac4126
-README.zh.md: 8679f2428a9e82a81de69d7d1413132a946fcafa
+README.md: 3ba247598f29f2244456061fe7f9a3282086148f
+README.zh.md: c13bc05b12fff2ef97b4d547936aa14a6556430a
--- a/packages/acp/README.md
+++ b/packages/acp/README.md
@@ -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.
--- a/packages/acp/README.zh.md
+++ b/packages/acp/README.zh.md
@@ -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 客户端都可以按照同一服务器契约驱动该服务器。
--- a/packages/acp/acp/README.i18n.yaml
+++ b/packages/acp/acp/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/acp/acp/README.md
-README.md: 583025e94d72c1ab03d282f8f4eb101c4e6f4740
-README.zh.md: 3a082b423c1e4ab7e236179a3f502cd450b4904c
+README.md: 9cc4a5e271c7200f6ad8799a4b8fa9e64b2ca893
+README.zh.md: 82aa5df2c7d87312d4b619a09582cc0c2d884398
--- a/packages/acp/acp/README.md
+++ b/packages/acp/acp/README.md
@@ -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. |
@@ -37,6 +37,8 @@ Committed-message output intentionally trades token-by-token latency for a clean

 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

 `pnpm --dir /path/to/deepseek-harness run demo:acp` boots the repository's automation server composition. A parent harness can spawn it through [`@deepseek-ai/dsh-subagent-acp`](../../subagent/subagent-acp/README.md); other ACP clients need only the core methods above.
--- a/packages/acp/acp/README.zh.md
+++ b/packages/acp/acp/README.zh.md
@@ -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、由桥接层拥有的批准请求提供一次性允许／拒绝选项。客户端可以自动回答。 |
@@ -37,6 +37,8 @@

 客户端断开与 Cordis 释放共用同一个记忆化清理流程。桥接层先拒绝新会话和提示词，结算待处理提示词，然后只 drain 此连接确切拥有的 Agent 之下的可继续后代，再并行释放这些 handle，并等待全部结果结算后才报告失败。其他共享该上下文的前端会保留其可继续森林和准入。因此，仅 ACP 的插件重载不会遗留 agent。

+ACP 要求每个提示词响应都携带 `stopReason`，但桥接层不声称它表示提示词专属的轮次结果。已提交的 assistant 消息会在整个自有活动期间流式输出，agent 进入 idle 前发生的 steering（中途引导）或注入工作也可能参与其中。因此，因 token 上限而结束的轮次不会成为提示词级 ACP 停止原因（它们以 `end_turn` 结算）；关联轮次上的模型错误会立即 reject 提示词。
+
 ## 运行

 `pnpm --dir /path/to/deepseek-harness run demo:acp` 启动仓库的自动化服务器组合。父 harness 可以通过 [`@deepseek-ai/dsh-subagent-acp`](../../subagent/subagent-acp/README.md) spawn 它；其他 ACP 客户端只需上述核心方法。
@@ -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 影响

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

 ## 已知限制与暂缓事项

--- a/packages/acp/acp/package.json
+++ b/packages/acp/acp/package.json
@@ -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": {
--- a/packages/acp/acp/src/codec.ts
+++ b/packages/acp/acp/src/codec.ts
@@ -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'
  }
--- a/packages/acp/acp/src/index.ts
+++ b/packages/acp/acp/src/index.ts
@@ -90,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
 }

@@ -149,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,
@@ -174,30 +171,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.
@@ -278,17 +278,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.
@@ -299,18 +300,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 }
--- a/packages/acp/acp/tests/approval.spec.ts
+++ b/packages/acp/acp/tests/approval.spec.ts
@@ -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 }
  }

--- a/packages/acp/acp/tests/codec.spec.ts
+++ b/packages/acp/acp/tests/codec.spec.ts
@@ -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('')
  })
 })
--- a/packages/acp/acp/tests/dispose.spec.ts
+++ b/packages/acp/acp/tests/dispose.spec.ts
@@ -67,7 +67,15 @@ describe('ACP connection ownership', () => {
    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') })
-    harness.ctx.on('agent/cancel-requested', () => { order.push('parent cancelled') })
+    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
--- a/packages/acp/acp/tests/turns.spec.ts
+++ b/packages/acp/acp/tests/turns.spec.ts
@@ -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') })
  })

@@ -49,12 +51,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) => {
@@ -65,13 +82,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' } }))
      }
@@ -86,30 +103,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)
@@ -143,7 +174,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 () => {
@@ -172,7 +235,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' }
@@ -184,7 +247,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 })
@@ -194,13 +257,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/)
+  })
 })
--- a/packages/bash/README.i18n.yaml
+++ b/packages/bash/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/bash/README.md
-README.md: ef82e9f4684ecf551ac7701d812088dd6b2ef6d0
-README.zh.md: 84ff244ec3d1ff5d385a3eb334e4cf9f1fe31e03
+README.md: 601782caad24d3555a206365a3f1954d81af1cf0
+README.zh.md: 8b96c4f80ba8776bfd8bdde178178cea946ff36c
--- a/packages/bash/README.md
+++ b/packages/bash/README.md
@@ -2,16 +2,16 @@

 English | [中文](README.zh.md)

-The capability family spans the canonical executor seam, its implementations, the shared shell environment, and the model-facing tools. All **product** packages.
+The capability family spans the canonical executor seam, its implementations, the shared shell environment, and the model-facing tools. All are **product** packages.

 | Package | Role | ctx key |
 |---|---|---|
-| `bash/` | Abstract bash executor seam (interface + vocabulary; sandbox result facts carry the [`sandbox/`](../sandbox/README.md) seam's mode/enforcement vocabulary, and the managed-env/output vocabulary is re-exported from the [`subprocess/`](../subprocess/README.md) seam) | `ctx.bash` |
-| `bash-local/` | Local `BashExecutor` implementation over the [`subprocess/`](../subprocess/README.md) service (command defaulting, deadlines, terminal env, background-read merge) | (registers `ctx.bash`) |
-| `bash-sandbox/` | Sandbox-consuming `BashExecutor` (wraps every command argv via `ctx.sandbox`, stamps denial/enforcement facts; extends `bash-local`'s mechanics) | (registers `ctx.bash`) |
-| `pwsh-local/` | Local PowerShell `BashExecutor` implementation over the [`subprocess/`](../subprocess/README.md) service (executable resolution, UTF-8-pinned spawn, Windows termination semantics) | (registers `ctx.bash`) |
-| `bash-env/` | Tool-independent managed `DSH_*` shell environment registry shared by the shell tools (built-in facts + effect-scoped contributors) | (registers `ctx.bashEnv`) |
-| `tool-bash/` | Model-facing `bash` schema; background processes register with the generic [`tasks/`](../tasks/README.md) runtime | (registers on `ctx.tools`) |
-| `tool-pwsh/` | Model-facing PowerShell-dialect `pwsh` schema (behavior mirrors `tool-bash` minus the sandbox surface); background processes register with the generic [`tasks/`](../tasks/README.md) runtime | (registers on `ctx.tools`) |
+| [`bash/`](bash/README.md) | Defines the executor contract shared by implementations and consumers. | `ctx.bash` |
+| [`bash-local/`](bash-local/README.md) | Executes commands through the local [`subprocess`](../subprocess/README.md) service. | (registers `ctx.bash`) |
+| [`bash-sandbox/`](bash-sandbox/README.md) | Applies the configured [`sandbox`](../sandbox/README.md) backend before local execution. | (registers `ctx.bash`) |
+| [`pwsh-local/`](pwsh-local/README.md) | Executes PowerShell commands with Windows-specific process behavior. | (registers `ctx.bash`) |
+| [`bash-env/`](bash-env/README.md) | Provides the managed `DSH_*` environment shared by shell tools. | `ctx.bashEnv` |
+| [`tool-bash/`](tool-bash/README.md) | Exposes Bash execution and background-task integration to the model. | (registers on `ctx.tools`) |
+| [`tool-pwsh/`](tool-pwsh/README.md) | Exposes PowerShell execution to the model. | (registers on `ctx.tools`) |

-The interface lives at `bash/bash/`. `bash-sandbox` replacing `bash-local` without touching the interface or the tool is the split doing exactly what it exists for — a leaf `cordis.yml` picks one executor entry, plus a `ctx.sandbox` provider entry for the confined one (see [the acp-agent example's default composition](../../examples/acp-agent/)).
+A leaf `cordis.yml` selects one executor implementation and the model-facing tools it needs. A sandboxed composition also selects a `ctx.sandbox` provider; the [ACP example](../../examples/acp-agent/) shows one complete wiring.
--- a/packages/bash/README.zh.md
+++ b/packages/bash/README.zh.md
@@ -1,17 +1,17 @@
-# bash/：bash 能力家族
+# bash/ — bash 能力家族

 [English](README.md) | 中文

-能力家族横跨规范执行器 seam、其实现、共享 shell 环境与面向模型的工具。这些全是**产品**包。
+该能力家族涵盖规范执行器 seam、其实现、共享 shell 环境和面向模型的工具。这些全是**产品**包。

 | 包 | 职责 | ctx key |
 |---|---|---|
-| `bash/` | 抽象 bash 执行器 seam（接口 + 词汇；沙箱结果事实携带 [`sandbox/`](../sandbox/README.md) seam 的模式／强制执行词汇，受管环境／输出词汇则从 [`subprocess/`](../subprocess/README.md) seam 重导出） | `ctx.bash` |
-| `bash-local/` | 构建在 [`subprocess/`](../subprocess/README.md) 服务之上的本地 `BashExecutor` 实现（命令默认值补全、deadline、终端环境、后台读取合并） | （注册 `ctx.bash`） |
-| `bash-sandbox/` | 消费沙箱的 `BashExecutor`（通过 `ctx.sandbox` 包装每个命令 argv，标记拒绝／强制执行事实；扩展 `bash-local` 的机制） | （注册 `ctx.bash`） |
-| `pwsh-local/` | 构建在 [`subprocess/`](../subprocess/README.md) 服务之上的本地 PowerShell `BashExecutor` 实现（可执行文件解析、UTF-8 固定 spawn、Windows 终止语义） | （注册 `ctx.bash`） |
-| `bash-env/` | 工具无关的受管 `DSH_*` shell 环境注册表，由 shell 工具共享（内置事实 + 受 effect 作用域约束的 contributor） | （注册 `ctx.bashEnv`） |
-| `tool-bash/` | 面向模型的 `bash` schema；后台进程注册到通用 [`tasks/`](../tasks/README.md) 运行时 | （注册到 `ctx.tools`） |
-| `tool-pwsh/` | 面向模型的 PowerShell 方言 `pwsh` schema（行为镜像 `tool-bash`，减去 sandbox 面）；后台进程注册到通用 [`tasks/`](../tasks/README.md) 运行时 | （注册到 `ctx.tools`） |
+| [`bash/`](bash/README.md) | 定义实现与消费方共享的执行器契约。 | `ctx.bash` |
+| [`bash-local/`](bash-local/README.md) | 通过本地 [`subprocess`](../subprocess/README.md) 服务执行命令。 | （注册 `ctx.bash`） |
+| [`bash-sandbox/`](bash-sandbox/README.md) | 在本地执行前应用已配置的 [`sandbox`](../sandbox/README.md) 后端。 | （注册 `ctx.bash`） |
+| [`pwsh-local/`](pwsh-local/README.md) | 以 Windows 专用进程行为执行 PowerShell 命令。 | （注册 `ctx.bash`） |
+| [`bash-env/`](bash-env/README.md) | 提供 shell 工具共享的托管 `DSH_*` 环境。 | `ctx.bashEnv` |
+| [`tool-bash/`](tool-bash/README.md) | 向模型公开 Bash 执行和后台任务集成。 | （注册到 `ctx.tools`） |
+| [`tool-pwsh/`](tool-pwsh/README.md) | 向模型公开 PowerShell 执行。 | （注册到 `ctx.tools`） |

-接口位于 `bash/bash/`。以 `bash-sandbox` 替换 `bash-local`，同时不改动接口或工具，正是这种拆分存在的意义：叶级 `cordis.yml` 选择一个执行器插件条目；受限实现还需再选择一个 `ctx.sandbox` 提供方插件条目（见 [acp-agent 示例的默认组合](../../examples/acp-agent/)）。
+叶节点 `cordis.yml` 选择一个执行器实现和所需的面向模型工具。沙箱化组合还会选择一个 `ctx.sandbox` 提供方；[ACP（Agent Client Protocol）示例](../../examples/acp-agent/)展示一套完整接线。
--- a/packages/bash/bash-env/README.i18n.yaml
+++ b/packages/bash/bash-env/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/bash/bash-env/README.md
 README.md: 7b939326d4effd14fc83ef0ad4e133f019f1011f
-README.zh.md: aeb33629def3fcc10294bbca19b37d43dcc73a0c
+README.zh.md: b6f3aca41771f1ca990a4b708cd53119b8e8ad78
--- a/packages/bash/bash-env/README.zh.md
+++ b/packages/bash/bash-env/README.zh.md
@@ -17,7 +17,7 @@

 ## Managed environment

-每次前台与后台模型 shell 调用都会收到一份新收集的受信任 `DSH_*` 环境。`DSH_HOME` 是由 [`@deepseek-ai/dsh-paths`](../../util/paths/README.md) 解析的 Harness 主目录绝对路径（`dshHome` 配置，然后环境变量 `$DSH_HOME`，然后 `~/.dsh`），`DSH_SHELL=1` 标识受管理的子进程。带 agent 的调用额外收到 `DSH_SESSION_ID=agent.session.header.id`；当活动的持久化 seam 定位到 JSONL 工件时，它们还会收到 `DSH_SESSION_JSONL=<绝对目标路径>`。JSONL 路径只是位置提示：首次 flush 之前它可能不存在，也不一定包含当前缓冲中的轮次，并且它不是授权凭据。
+每次前台与后台模型 shell 调用都会收到一份新收集的受信任 `DSH_*` 环境。`DSH_HOME` 是由 [`@deepseek-ai/dsh-paths`](../../util/paths/README.md) 解析的 Harness 主目录绝对路径（`dshHome` 配置，然后环境变量 `$DSH_HOME`，然后 `~/.dsh`），`DSH_SHELL=1` 标识受管理的子进程。带 agent（智能体）的调用额外收到 `DSH_SESSION_ID=agent.session.header.id`；当活动的持久化 seam 定位到 JSONL 工件时，它们还会收到 `DSH_SESSION_JSONL=<绝对目标路径>`。JSONL 路径只是位置提示：首次 flush 之前它可能不存在，也不一定包含当前缓冲中的轮次，并且它不是授权凭据。

 `ctx.bashEnv` 负责收集。其他插件可以注册一个受 effect 作用域约束的 contributor，带有稳定名称、已声明的键/描述以及 `resolve(execution: ToolExecution)`；重复所有权与未声明的运行时键会响亮失败，而 `list()` 只枚举声明、不执行 provider。Harness 内置键保留 `DSH_HOME`、`DSH_SHELL` 与 `DSH_SESSION_ID`；本插件的持久化翻译器通过读取与后端无关的 `sessionPersistence.locate()` seam 拥有 `DSH_SESSION_JSONL`。

--- a/packages/bash/bash-env/package.json
+++ b/packages/bash/bash-env/package.json
@@ -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",
  "peerDependencies": {
--- a/packages/bash/bash-local/README.i18n.yaml
+++ b/packages/bash/bash-local/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/bash/bash-local/README.md
-README.md: 9b01f1ce9d046062e55037ba13e8f74b95ef1161
-README.zh.md: fde3eb77f72337d54c91c1a40fb87cb3d13652e7
+README.md: cb40cb8fa40d95d5b4589b7c804f450a2bf38c8e
+README.zh.md: bd4f73babdb47ff92e87e20eb7d60657ed515ec4
--- a/packages/bash/bash-local/README.md
+++ b/packages/bash/bash-local/README.md
@@ -20,15 +20,13 @@ The package root exports the default and named `LocalBashExecutor` plugin plus i
    graceMs: 3000              # kill escalation and post-exit pipe-drain grace
 ```

-## Behavior (and where it came from)
+## Behavior

-Design surveyed against the bash tools of Claude Code, OpenCode, Codex, and pi; the notable choices:
-
- **Spawn per call, no shell state** — every call is a fresh non-login `bash -c` (deterministic; no rc files). All four surveyed tools spawn per call. `XXX(stateful-shell)` in `src/index.ts` records the two proven stateful designs (Claude Code's cwd-only persistence; Codex's PTY exec sessions) for when real workflows demand them.
- **Configured budgets over managed groups** — `resolve()` fills `workdir`/`timeoutMs`/`stdoutMaxBytes` from config, and every spawn hands the service explicit byte caps, spill cap, and `graceMs` (default 3s — OpenCode's escalation). The grace must be positive, finite, and no greater than [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md), so Node can represent it with one timer. Process-group kills, the post-exit pipe-drain grace, tail-keep truncation, and bounded spill files are [`dsh-subprocess-local`](../../subprocess/subprocess-local/README.md) mechanics. A foreground `BashExecRequest.stdoutMaxBytes` can raise stdout's capture budget for one trusted caller; stderr and background runs still use `maxOutputBytes`.
+- **Spawn per call, no shell state** — every call is a fresh non-login `bash -c` with no rc files.
+- **Configured budgets over managed groups** — `resolve()` fills `workdir`/`timeoutMs`/`stdoutMaxBytes` from config, and every spawn hands the service explicit byte caps, spill cap, and `graceMs`. The grace must be positive, finite, and no greater than [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md), so Node can represent it with one timer. Process-group kills, post-exit pipe draining, tail retention, and bounded spill files are [`dsh-subprocess-local`](../../subprocess/subprocess-local/README.md) mechanics. A foreground `BashExecRequest.stdoutMaxBytes` can raise stdout's capture budget for one trusted caller; stderr and background runs still use `maxOutputBytes`.
 - **Timeout and cancel classification** — `run()` fuses its config-clamped timeout with the caller's signal through one deadline; only the executor's own timeout reports `timedOut`, an upstream cancel reports `aborted`, and a self-signaled command reports neither ([timeout-library Agent Note](../../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md)).
- **Model-friendly terminal env** — `NO_COLOR=1 TERM=dumb PAGER=cat GIT_PAGER=cat` (Codex's hardcoded set) so pagers and ANSI color don't garble results, merged as ordinary env under the service's credential scrub and `DSH_*` channel rules; an explicit caller entry still wins. See the [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) and [managed environment Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md).
- **Background processes** — `start()` returns a live `BashProcess` handle immediately, no timeout applies (Claude Code detaches timeouts when backgrounding), and the handle's `readOutput()` merges the service's offset-based stdout/stderr reads into one marked-section delta with a consuming cursor. A still-running process belongs to the subprocess service, so it survives executor reloads and dies (killed and joined) with the service's disposal. Everything task-shaped (ids, ownership, polling, notices) lives in the generic [`ctx.tasks` runtime](../../tasks/tasks/README.md), which the tool layer registers the handle with — this executor never sees a session or a registry.
+- **Model-friendly terminal env** — `NO_COLOR=1 TERM=dumb PAGER=cat GIT_PAGER=cat` prevents pagers and ANSI color from garbling results. These values merge as ordinary env under the service's credential scrub and `DSH_*` channel rules; an explicit caller entry still wins. See the [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) and [managed environment Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md).
+- **Background processes** — `start()` returns a live `BashProcess` handle immediately with no timeout, and `readOutput()` merges offset-based stdout/stderr reads into one consuming delta, placing stderr under a `[stderr]` marker when present. A running process belongs to the subprocess service, survives executor reloads, and is killed and joined on service disposal. Task ids, ownership, polling, and notices belong to the generic [`ctx.tasks` runtime](../../tasks/tasks/README.md), which the tool layer registers the handle with.

 ## Model Experience

--- a/packages/bash/bash-local/README.zh.md
+++ b/packages/bash/bash-local/README.zh.md
@@ -20,15 +20,13 @@
    graceMs: 3000              # kill escalation and post-exit pipe-drain grace
 ```

-## 行为（以及设计来源）
+## 行为

-设计时调研了 Claude Code、OpenCode、Codex 和 pi 的 bash 工具，主要取舍如下：
-
- **每次调用都 spawn，不保留 shell 状态**：每次调用都启动新的非登录 `bash -c`（行为确定，不读取 rc 文件）。调研的四种工具均会每次调用单独 spawn。`XXX(stateful-shell)` 位于 `src/index.ts`，记录了两种已验证的有状态设计（Claude Code 仅持久化 cwd；Codex 使用 PTY exec 会话），供真实工作流需要时采用。
- **在受管进程组之上应用配置预算**：`resolve()` 从配置补全 `workdir`／`timeoutMs`／`stdoutMaxBytes`，每次 spawn 都向服务传入显式的字节上限、spill 上限与 `graceMs`（默认 3 秒，沿用 OpenCode 的升级策略）。该宽限期须为正有限值，且不得大于 [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md)，这样 Node 就能用一个定时器表示它。进程组终止、退出后的管道排空宽限期、尾部保留截断与有界 spill 文件是 [`dsh-subprocess-local`](../../subprocess/subprocess-local/README.md) 的机制。前台 `BashExecRequest.stdoutMaxBytes` 可为某个受信任调用方提高单次 stdout 捕获预算；stderr 和后台运行仍使用 `maxOutputBytes`。
- **超时与取消分类**：`run()` 通过同一个 deadline 把经配置钳位的超时与调用方的信号融合；只有执行器自身的超时报告 `timedOut`，上游取消报告 `aborted`，自身因信号终止的命令两者皆不报告（见[超时库 Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md)）。
- **适合模型的终端环境**：设置 `NO_COLOR=1 TERM=dumb PAGER=cat GIT_PAGER=cat`（Codex 硬编码的集合），防止分页器与 ANSI 颜色破坏结果；这些条目作为普通 env 合并，遵循服务的凭据清除与 `DSH_*` 通道规则；调用方的显式条目依旧优先。详见 [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) 与 [受管环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。
- **后台进程**：`start()` 会立即返回活动的 `BashProcess` 句柄，不应用超时（Claude Code 在转为后台时会解除超时）；句柄的 `readOutput()` 把服务基于偏移量的 stdout/stderr 读取合并为一条带分节标记的增量，并以消费游标记录读取进度。仍在运行的进程则由 subprocess 服务负责，因此它能在执行器重载后存活，并随服务的 dispose 被终止且等待退出。所有具有任务形态的事项（id、所有权、轮询、通知）都属于通用 [`ctx.tasks` 运行时](../../tasks/tasks/README.md)，工具层会在其中注册该句柄；本执行器不会接触会话或注册表。
+- **每次调用都 spawn，不保留 shell 状态**：每次调用都启动新的非登录 `bash -c`，且不读取 rc 文件。
+- **在受管进程组之上应用配置预算**：`resolve()` 从配置补全 `workdir`／`timeoutMs`／`stdoutMaxBytes`，每次 spawn 都向服务传入显式的字节上限、spill 上限与 `graceMs`。该宽限期须为正有限值，且不得大于 [`MAX_TIMER_DELAY_MS`](../../util/timeout/README.md)，这样 Node 就能用一个定时器表示它。进程组终止、退出后管道排空、尾部保留与有界 spill 文件是 [`dsh-subprocess-local`](../../subprocess/subprocess-local/README.md) 的机制。前台 `BashExecRequest.stdoutMaxBytes` 可为某个受信任调用方提高单次 stdout 捕获预算；stderr 和后台运行仍使用 `maxOutputBytes`。
+- **超时与取消分类**：`run()` 通过同一个 deadline 把经配置钳位的超时与调用方的信号融合；只有执行器自身的超时报告 `timedOut`，上游取消报告 `aborted`，自身因信号终止的命令两者皆不报告（见[超时库 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md)）。
+- **适合模型的终端环境**：`NO_COLOR=1 TERM=dumb PAGER=cat GIT_PAGER=cat` 防止分页器与 ANSI 颜色破坏结果。这些值作为普通 env 合并，遵循服务的凭据清除与 `DSH_*` 通道规则；调用方的显式条目依旧优先。详见 [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) 与 [受管环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。
+- **后台进程**：`start()` 会立即返回活动的 `BashProcess` 句柄且不应用超时；`readOutput()` 把基于偏移量的 stdout/stderr 读取合并为一条消费式增量，并在存在 stderr 时将其置于 `[stderr]` 标记下。运行中的进程属于 subprocess 服务，可在执行器重载后存活，并在服务 dispose 时被终止且等待退出。task id、所有权、轮询和通知属于通用 [`ctx.tasks` 运行时](../../tasks/tasks/README.md)，工具层会在其中注册该句柄。

 ## 模型体验

--- a/packages/bash/bash-local/package.json
+++ b/packages/bash/bash-local/package.json
@@ -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",
  "peerDependencies": {
--- a/packages/bash/bash-local/src/index.ts
+++ b/packages/bash/bash-local/src/index.ts
@@ -1,10 +1,11 @@
 /**
 * Local implementation of the bash executor seam over the subprocess
- * seam. Each command runs as `bash -c` in a managed process group spawned
- * through `ctx.subprocess`; this executor owns command defaulting, deadlines
- * and cause classification, the model-friendly terminal environment, and the
- * model-facing stdout/stderr merge for background reads. Execution policy
- * belongs in `tools/pre-execute` or a sandboxing executor.
+ * seam. Public commands run as `bash -c` in a managed process group spawned
+ * through `ctx.subprocess`; subclasses may reuse the same mechanics with an
+ * explicit argv. This executor owns command defaulting, deadlines and cause
+ * classification, the model-friendly terminal environment, and the model-facing
+ * stdout/stderr merge for background reads. Execution policy belongs in
+ * `tools/pre-execute` or a sandboxing executor.
 * @module @deepseek-ai/dsh-bash-local
 */

@@ -140,13 +141,18 @@ export class LocalBashExecutor extends BashExecutor {
    }
  }

-  /** Map one resolved bash spec onto a fully-specified subprocess spawn. */
+  /** Map one resolved bash spec and explicit argv onto a fully-specified subprocess spawn. */
  // XXX(stateful-shell): evaluate persistent cwd or PTY sessions when workflows require shell state.
-  private spawnSpec(spec: BashExecSpec, stdoutMaxBytes: number, signal: AbortSignal | undefined): SubprocessSpawnSpec {
+  private spawnSpec(
+    spec: BashExecSpec,
+    argv: readonly string[],
+    stdoutMaxBytes: number,
+    signal: AbortSignal | undefined,
+  ): SubprocessSpawnSpec {
    const collect = (maxBytes: number): SubprocessCollect =>
      ({ maxBytes, spill: { maxBytes: this.config.maxSpillBytes } })
    return {
-      argv: ['bash', '-c', spec.command],
+      argv,
      cwd: spec.workdir,
      stdio: {
        stdin: spec.stdin !== undefined ? { data: spec.stdin } : 'ignore',
@@ -174,9 +180,21 @@ export class LocalBashExecutor extends BashExecutor {
  }

  async run(spec: BashExecSpec): Promise<BashRunResult> {
+    return this.runArgv(spec, ['bash', '-c', spec.command])
+  }
+
+  /**
+   * Run an explicit argv with the foreground lifecycle, environment, output,
+   * timeout, and cancellation semantics of this executor. Subclasses use this
+   * after replacing the public command's shell argv at an execution boundary.
+   * @param spec - resolved execution settings and caller-owned command metadata.
+   * @param argv - exact executable and arguments to hand to `ctx.subprocess`.
+   * @returns the settled foreground result with collected output and cause facts.
+   */
+  protected async runArgv(spec: BashExecSpec, argv: readonly string[]): Promise<BashRunResult> {
    // One deadline combines timeout and upstream cancellation; disposal clears its timer.
    using d = deadline(spec.signal, spec.timeoutMs, 'BASH_TIMEOUT')
-    const handle = this.ctx.subprocess.spawn(this.spawnSpec(spec, spec.stdoutMaxBytes, d.signal))
+    const handle = this.ctx.subprocess.spawn(this.spawnSpec(spec, argv, spec.stdoutMaxBytes, d.signal))
    const outcome = await handle.done
    const collected = LocalBashExecutor.collected(handle)
    // Only this executor's timeout reason counts as timedOut; outer deadlines count as aborts.
@@ -193,8 +211,21 @@ export class LocalBashExecutor extends BashExecutor {
  }

  start(spec: BashExecSpec): BashProcess {
+    return this.startArgv(spec, ['bash', '-c', spec.command])
+  }
+
+  /**
+   * Start an explicit argv with the background lifecycle, environment, output,
+   * cancellation, and process-tree ownership semantics of this executor.
+   * Subclasses use this after replacing the public command's shell argv at an
+   * execution boundary.
+   * @param spec - resolved execution settings and caller-owned command metadata.
+   * @param argv - exact executable and arguments to hand to `ctx.subprocess`.
+   * @returns the live background handle; spawn rejection settles it as killed.
+   */
+  protected startArgv(spec: BashExecSpec, argv: readonly string[]): BashProcess {
    // Background runs ignore timeoutMs; callers stop them through kill() or spec.signal.
-    const running = this.ctx.subprocess.spawn(this.spawnSpec(spec, this.config.maxOutputBytes, spec.signal))
+    const running = this.ctx.subprocess.spawn(this.spawnSpec(spec, argv, this.config.maxOutputBytes, spec.signal))
    const collected = LocalBashExecutor.collected(running)

    // A spawn failure produces no process output, so the subprocess service has nothing
@@ -219,12 +250,12 @@ export class LocalBashExecutor extends BashExecutor {
        }
        proc.exitCode = outcome.exitCode
        proc.signal = outcome.signal
-        this.onProcessDone(proc, collected.stderr.readFrom(0).text)
+        this.onProcessDone(proc, collected.stderr.readFrom(0).text, false)
      }, (error: unknown) => {
        // Background spawn failures settle as killed and surface through the read path.
        proc.status = 'killed'
        spawnFailureNote = `spawn failed: ${String(error)}`
-        this.onProcessDone(proc, spawnFailureNote)
+        this.onProcessDone(proc, spawnFailureNote, true, error)
      }),
      readOutput: (): BashProcessRead => {
        const out = collected.stdout.readFrom(stdoutOffset)
@@ -264,8 +295,10 @@ export class LocalBashExecutor extends BashExecutor {
   * empty.
   * @param _proc - the settled process handle.
   * @param _stderr - the process's retained stderr tail used by subclasses for settlement classification.
+   * @param _spawnFailed - whether the subprocess promise rejected before a process started.
+   * @param _spawnError - the original spawn rejection reason, which may itself be undefined.
   */
-  protected onProcessDone(_proc: BashProcess, _stderr: string): void {}
+  protected onProcessDone(_proc: BashProcess, _stderr: string, _spawnFailed: boolean, _spawnError?: unknown): void {}
 }

 export default LocalBashExecutor
--- a/packages/bash/bash-sandbox/README.i18n.yaml
+++ b/packages/bash/bash-sandbox/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/bash/bash-sandbox/README.md
-README.md: 035a8ad2401ca608d264049d454359eda7b2b9a7
-README.zh.md: cee27a9baaa539ba07eb1d730ea9bef2004fbeeb
+README.md: 74c1e28f76db35603bb9f72e0522e16ece5589f7
+README.zh.md: 2593049ce09c7bc1ae0a996321bb27cbac449977
--- a/packages/bash/bash-sandbox/README.md
+++ b/packages/bash/bash-sandbox/README.md
@@ -4,9 +4,9 @@ English | [中文](README.zh.md)

 Sandbox-consuming implementation of the [`@deepseek-ai/dsh-bash`](../bash/) executor seam. Load it **instead of** `@deepseek-ai/dsh-bash-local`, together with a [`ctx.sandbox`](../../sandbox/sandbox/) provider (e.g. [`@deepseek-ai/dsh-sandbox-local`](../../sandbox/sandbox-local/)) and a [`ctx.sandboxPolicy`](../../sandbox/sandbox-policy/) (which owns the default mode + workspace root, shared with the sandboxed filesystem) — no alternate tool plugin is needed; `dsh-tool-bash` detects the executor's `sandboxMode` capability and adds the escalation fields.

-The package root exports the default and named `SandboxBashExecutor` plugin plus its `Config`; quoting and result-classification helpers stay internal.
+The package root exports the default and named `SandboxBashExecutor` plugin plus its `Config`; result-classification helpers stay internal.

-Every command is confined by handing the provider the exact `['bash', '-c', command]` argv this executor is about to spawn and spawning the returned (wrapped) argv instead. WHICH platform runner confines it — and whether one is usable at all (fail closed with a structured `SANDBOX_UNAVAILABLE` error, never a silent unconfined run) — is the provider's concern; this package owns the bash side only.
+Every command is confined by handing the provider the exact `['bash', '-c', command]` argv this executor is about to spawn and spawning the returned argv directly. With the shipped native runners, the inner Bash retains shell semantics and evaluates `BASH_ENV` only after the runner establishes confinement. WHICH platform runner confines it — and whether one is usable at all (fail closed with a structured `SANDBOX_UNAVAILABLE` error, never a silent unconfined run) — is the provider's concern; this package owns the bash side only.

 | Mode | File effects |
 |---|---|
@@ -17,7 +17,7 @@ Every command is confined by handing the provider the exact `['bash', '-c', comm
 Semantics:

 - **Denials are result facts.** A failed run whose stderr carries the selected backend's own denial dialect — the signatures the provider stamps on every wrap (EROFS text under bwrap, EACCES under Landlock, EPERM under Seatbelt) — is reported as `BashRunResult.sandbox.denied: true` (conservative classification, read from the collected stderr tail); every CONFINED run also carries the mode it executed under (`result.sandbox.mode`) and the provider's enforcement completeness (`result.sandbox.enforcement`: `full`, or `partial` on an older Landlock ABI).
- **Runner failures are sandbox failures, never command failures.** Foreground execution throws `SANDBOX_UNAVAILABLE`; a settled background process stamps `process.sandbox.runnerFailed`, which the bash producer renders through generic `task_output`. Spawn failures also pass through settlement, so confined background handles retain their mode/enforcement facts and release per-process accounting.
+- **Runner attribution is conservative.** Before a process starts, a rejection is attributed to the runner only when the caller-owned workdir is independently usable and Node reports `ENOENT` or `EACCES` with positive provenance for provider argv[0]. This covers a missing runner, a non-executable runner, or an executable script whose shebang interpreter is unavailable. A bare `syscall: 'spawn'` without an exact error path, any other code, an invalid or unusable workdir, a resource failure, an unrelated syscall, or an unstructured rejection retains the local executor's command-start failure semantics. Foreground execution throws `SANDBOX_UNAVAILABLE` with the original spawn detail, while asynchronous background settlement stamps `runnerFailed: true` and `denied: false`. If a `SubprocessService` synchronously throws the same provenanced `ENOENT`/`EACCES` shape, background start throws `SANDBOX_UNAVAILABLE`; other synchronous errors propagate unchanged. After a process starts, a rule's optional exit-code gate and a remaining fatal stderr line must both match after exact informational-line exclusions. A match outranks denial; foreground execution throws `SANDBOX_UNAVAILABLE` with the matched fatal line, while a settled background process stamps `process.sandbox.runnerFailed`, which the bash producer renders through generic `task_output`. Confined background handles retain their mode/enforcement facts and release per-process accounting in either path.
 - **Deployment fallback, per-call policy.** [`ctx.sandboxPolicy`](../../sandbox/sandbox-policy/) resolves a complete `SandboxExecutionPolicy` for every tool call: the calling session supplies its mode override and immutable cwd root, while deployment config supplies the fallbacks for agentless calls. An approved escalation changes only that policy's mode; its session root stays attached. `resolve()` carries the policy onto the spec, so overlapping commands from different projects run, classify, and report under their own roots and modes. The capability fact `ctx.bash.sandboxMode` reports the configured default so the tool layer advertises escalation only when this executor is mounted; the static bash tool description separately owns denial and escalation guidance.
 - **File effects only.** Network and process visibility are deliberately not restricted — the mode vocabulary does not pretend to cover what the backend does not enforce.
 - Process mechanics (spawn, process-group kills, output collection/spill, background handles, credential scrub) are inherited from [`dsh-bash-local`](../bash-local/); runner selection lives in [`dsh-sandbox-local`](../../sandbox/sandbox-local/).
@@ -36,8 +36,6 @@ Deny-only at the seam: a denial is a reported fact, and this executor never nego
  name: '@deepseek-ai/dsh-bash-sandbox'
 ```

-The keyless consumer-integration proofs are `tests/bwrap.e2e.ts`, `tests/landlock.e2e.ts`, and `tests/seatbelt.e2e.ts` (the real provider + real runner driven through `ctx.bash`, world-verified, each self-skipping where its runner is absent). The agent-spine e2e additionally drives two concurrent sessions in one Cordis context and proves each real bash tool call can write only its own project. See [the acp-agent example's default composition](../../../examples/acp-agent/) for the runnable demo.
-
 ## Model Experience

 ### Bash tool schema, indirectly
@@ -72,7 +70,7 @@ Append-only; newly visible content follows the reusable request prefix and does

 #### What the model sees

-If no runner can enforce a confined mode, the foreground call propagates the [`SANDBOX_UNAVAILABLE` error owned by `dsh-sandbox`](../../sandbox/sandbox/README.md#confinement-error-indirectly). For an execution-time runner failure, this backend supplies the first stderr line as its detail.
+If no runner can enforce a confined mode, the foreground call propagates the [`SANDBOX_UNAVAILABLE` error owned by `dsh-sandbox`](../../sandbox/sandbox/README.md#confinement-error-indirectly). A runner-attributable spawn failure supplies the original spawn error as detail; a rejection without `ENOENT`/`EACCES` argv[0] evidence remains an ordinary command-start error. A settled runner failure supplies the matched fatal stderr line and preserves the original stderr collection. When present, the appended `Runner failure: <detail>` is the authoritative diagnosis; the preceding backend-install text is the generic `SANDBOX_UNAVAILABLE` prefix.

 #### Token effect

@@ -86,5 +84,5 @@ Append-only; newly visible content follows the reusable request prefix and does

 - **Confinement covers file effects only** — network access and process visibility are unchanged, so the modes are not a general-purpose security sandbox.
 - **Denials are inferred from failed-command stderr** — backend signatures make the inference portable, but a matching application error can be classified as a denial and a denial omitted from the retained tail can be missed.
- **A background runner failure has no immediate error channel** — it is recorded on the settled process and surfaces when the caller reads the generic task with `task_output`.
+- **An asynchronously observed background runner failure has no immediate error channel** — it is recorded on the settled process and surfaces when the caller reads the generic task with `task_output`; a provenanced synchronous `SubprocessService` throw instead fails `start()` immediately.
 - **`danger-full-access` deliberately bypasses `ctx.sandbox`** — it is an explicit unconfined mode, not a wider sandbox profile.
--- a/packages/bash/bash-sandbox/README.zh.md
+++ b/packages/bash/bash-sandbox/README.zh.md
@@ -4,9 +4,9 @@

 这是使用沙箱能力的 [`@deepseek-ai/dsh-bash`](../bash/) 执行器 seam 实现。加载它时，应**用它替代** `@deepseek-ai/dsh-bash-local`，并同时加载 [`ctx.sandbox`](../../sandbox/sandbox/) 提供方（例如 [`@deepseek-ai/dsh-sandbox-local`](../../sandbox/sandbox-local/)）及 [`ctx.sandboxPolicy`](../../sandbox/sandbox-policy/)；默认模式和工作区根目录由后者负责，并与受沙箱约束的文件系统共享这些设置。无需使用替代工具插件；`dsh-tool-bash` 会检测执行器的 `sandboxMode` 能力并添加升权字段。

-包根目录导出默认与具名的 `SandboxBashExecutor` 插件及其 `Config`；引号处理与结果分类 helper 保留在内部。
+包根目录导出默认与具名的 `SandboxBashExecutor` 插件及其 `Config`；结果分类 helper 保留在内部。

-每条命令的限制方式都是：把本执行器即将 spawn 的精确 `['bash', '-c', command]` argv 交给提供方，再 spawn 其返回的（已包装）argv。由哪种平台 runner 执行限制，以及是否有 runner 可用，属于提供方职责；若无可用 runner，则按失败关闭原则拒绝执行并返回结构化 `SANDBOX_UNAVAILABLE` 错误，绝不能静默地无约束运行。本包只负责 bash 侧。
+每条命令的限制方式都是：把本执行器即将 spawn 的精确 `['bash', '-c', command]` argv 交给提供方，并直接 spawn 返回的 argv。使用随附的原生 runner 时，内层 Bash 保留 shell 语义，并且只在 runner 建立约束后才求值 `BASH_ENV`。由哪种平台 runner 执行限制，以及是否有 runner 可用，属于提供方职责；若无可用 runner，则按失败关闭原则拒绝执行并返回结构化 `SANDBOX_UNAVAILABLE` 错误，绝不能静默地无约束运行。本包只负责 bash 侧。

 | 模式 | 文件影响 |
 |---|---|
@@ -17,7 +17,7 @@
 语义：

 - **拒绝是结果事实。** 如果一次失败运行的 stderr 包含所选后端自身的拒绝方言，即提供方在每次包装时加上的特征（bwrap 下的 EROFS 文本、Landlock 下的 EACCES、Seatbelt 下的 EPERM），则结果报告 `BashRunResult.sandbox.denied: true`（从已收集的 stderr 尾部进行保守分类）。每次受限制运行还会携带执行时模式（`result.sandbox.mode`）与提供方强制执行完整性（`result.sandbox.enforcement`：`full`，或在较旧 Landlock ABI 上为 `partial`）。
- **Runner 失败是沙箱失败，绝不是命令失败。** 前台执行会抛出 `SANDBOX_UNAVAILABLE`；已结算的后台进程会标记 `process.sandbox.runnerFailed`，Bash 结果生成方通过通用 `task_output` 渲染它。spawn 失败也会经过结算，因此受限制的后台句柄会保留自身的模式／强制执行事实，并释放每进程计数。
+- **Runner 归因是保守的。** 进程启动前，只有当调用方拥有的 workdir 经独立验证可用，并且 Node 报告 `ENOENT` 或 `EACCES`，且带有明确指向提供方 argv[0] 的来源信息时，才会将拒绝归因于 runner。这样可以识别缺失的 runner、不可执行的 runner，或 shebang 解释器不可用的可执行脚本。没有精确错误路径的裸 `syscall: 'spawn'`、任何其他错误码、无效或不可用的 workdir、资源失败、无关 syscall 或无结构拒绝仍保留本地执行器的命令启动失败语义。前台执行会抛出 `SANDBOX_UNAVAILABLE` 并附带原始 spawn 错误详情，异步后台结算则会标记 `runnerFailed: true` 和 `denied: false`。如果 `SubprocessService` 同步抛出同样带有来源信息的 `ENOENT`／`EACCES` 形态，后台启动会抛出 `SANDBOX_UNAVAILABLE`；其他同步错误原样传播。进程启动后，先按整行精确匹配排除信息性行，随后规则的可选退出码门控和余下 stderr 中的一行致命诊断必须同时匹配。匹配结果优先于拒绝；前台执行会抛出 `SANDBOX_UNAVAILABLE` 并附带匹配到的致命行，已结算的后台进程则会标记 `process.sandbox.runnerFailed`，Bash 结果生成方通过通用 `task_output` 渲染它。无论走哪条路径，受限制的后台句柄都会保留自身的模式／强制执行事实，并释放每进程计数。
 - **部署回退，每次调用策略。** [`ctx.sandboxPolicy`](../../sandbox/sandbox-policy/) 为每次工具调用解析完整的 `SandboxExecutionPolicy`：调用会话提供自身的模式覆盖与不可变 cwd 根目录，部署配置则为无 agent（智能体）调用提供回退。已批准的升权只更改该策略的模式，会话根目录仍然附着其上。`resolve()` 把策略带入 spec，因此来自不同项目的重叠命令会在各自的根目录与模式下运行、分类和报告。能力事实 `ctx.bash.sandboxMode` 报告已配置的默认值，因此工具层只在装载该执行器时才公布升权；静态 bash 工具描述则单独负责拒绝与升级引导。
 - **只限制文件影响。** 设计上不限制网络与进程可见性：模式词汇不会声称覆盖后端未强制执行的范围。
 - 进程机制（spawn、进程组终止、输出收集／spill、后台句柄、凭证清理）继承自 [`dsh-bash-local`](../bash-local/)；runner 选择位于 [`dsh-sandbox-local`](../../sandbox/sandbox-local/)。
@@ -36,8 +36,6 @@
  name: '@deepseek-ai/dsh-bash-sandbox'
 ```

-无密钥消费方集成证明是 `tests/bwrap.e2e.ts`、`tests/landlock.e2e.ts` 和 `tests/seatbelt.e2e.ts`（通过 `ctx.bash` 驱动真实提供方 + 真实 runner，从外部验证实际文件效果，并在相应 runner 缺失时各自自行跳过）。agent-spine e2e 还会在一个 Cordis 上下文中驱动两个并发会话，并证明每个真实 bash 工具调用只能写入自身项目。可运行 demo 见 [acp-agent 示例的默认组合](../../../examples/acp-agent/)。
-
 ## 模型体验

 ### 间接的 Bash 工具 schema
@@ -72,7 +70,7 @@

 #### 模型看到的内容

-如果没有 runner 能强制执行受限模式，前台调用会传播 [`SANDBOX_UNAVAILABLE` 错误](../../sandbox/sandbox/README.md#confinement-error-indirectly)；该错误由 `dsh-sandbox` 定义。如果 runner 在执行时失败，此后端会提供第一行 stderr 作为详细信息。
+如果没有 runner 能强制执行受限模式，前台调用会传播 [`SANDBOX_UNAVAILABLE` 错误](../../sandbox/sandbox/README.md#confinement-error-indirectly)；该错误由 `dsh-sandbox` 定义。可归因于 runner 的 spawn 失败会以原始 spawn 错误作为详细信息；没有 `ENOENT`／`EACCES` argv[0] 证据的拒绝仍是普通的命令启动错误。已结算的 runner 失败则以匹配到的致命 stderr 行作为详细信息，并保留原始 stderr 收集结果。如果追加了 `Runner failure: <detail>`，它就是权威诊断；前面的后端安装文本只是通用的 `SANDBOX_UNAVAILABLE` 前缀。

 #### Token 影响

@@ -86,5 +84,5 @@

 - **限制只覆盖文件影响**：网络访问与进程可见性不变，因此这些模式不是通用安全沙箱。
 - **拒绝从失败命令的 stderr 推断**：后端特征使该推断可跨平台使用，但包含相同后端特征的应用错误可能被分类为拒绝，也可能遗漏未出现在保留尾部中的拒绝。
- **后台 runner 失败没有即时错误通道**：它记录在已结算进程上，并在调用方使用 `task_output` 读取通用任务时呈现。
+- **异步观测到的后台 runner 失败没有即时错误通道**：它记录在已结算进程上，并在调用方使用 `task_output` 读取通用任务时呈现；同步 `SubprocessService` 抛出带有来源信息的 `ENOENT`／`EACCES` 时，则会使 `start()` 立即失败。
 - **`danger-full-access` 有意绕过 `ctx.sandbox`**：它是显式无约束模式，不是更宽的沙箱 profile。
--- a/packages/bash/bash-sandbox/package.json
+++ b/packages/bash/bash-sandbox/package.json
@@ -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",
  "peerDependencies": {
--- a/packages/bash/bash-sandbox/src/helpers.ts
+++ b/packages/bash/bash-sandbox/src/helpers.ts
@@ -1,18 +1,61 @@
 /**
- * Internal shell-quoting and sandbox-result classification helpers.
+ * Internal sandbox-result classification helpers.
 *
 * @module @deepseek-ai/dsh-bash-sandbox/helpers
 */

+import { accessSync, constants, statSync } from 'node:fs'
 import type { BashRunResult } from '@deepseek-ai/dsh-bash'
+import type { RunnerFailureRule } from '@deepseek-ai/dsh-sandbox'
+
+/** Node-local spawn codes proven to identify executable resolution or permission failure. */
+const EXECUTABLE_SPAWN_CODES = new Set(['EACCES', 'ENOENT'])
+
+/** Whether the caller-owned spawn cwd can be entered. */
+function isUsableWorkdir(path: string): boolean {
+  try {
+    if (!statSync(path).isDirectory()) return false
+    accessSync(path, constants.X_OK)
+    return true
+  } catch {
+    return false
+  }
+}

 /**
- * Quote one string as a single-quoted POSIX shell word.
- * @param text - raw argv element to preserve through the outer shell parse.
- * @returns the quoted shell word.
+ * Attribute only Node ENOENT/EACCES failures with positive argv[0] provenance
+ * after independently ruling out the caller-owned cwd. A supplied error path
+ * must exactly identify the runner; without one, the syscall must. With a
+ * usable cwd, these codes describe resolution or execute permission for that
+ * argv[0] or its shebang interpreter.
+ * The workdir is checked at classification time, not atomically with spawn;
+ * concurrent path replacement may change attribution but cannot permit an
+ * unconfined execution.
+ * @param error - the original spawn rejection.
+ * @param runnerProgram - provider argv[0], the executable that establishes confinement.
+ * @param workdir - the caller-owned spawn cwd, checked independently for usability.
+ * @returns whether the rejection has executable-specific runner evidence.
 */
-export function shellQuote(text: string): string {
-  return `'${text.replaceAll("'", String.raw`'\''`)}'`
+export function isRunnerSpawnFailure(
+  error: unknown,
+  runnerProgram: string | undefined,
+  workdir: string,
+): boolean {
+  if (runnerProgram === undefined || !isUsableWorkdir(workdir)) return false
+  if (typeof error !== 'object' || error === null) return false
+  const { code, path, syscall } = error as { code?: unknown; path?: unknown; syscall?: unknown }
+  if (typeof code !== 'string' || !EXECUTABLE_SPAWN_CODES.has(code)) return false
+  if (typeof syscall !== 'string') return false
+  const exactSyscall = `spawn ${runnerProgram}`
+  if (path === undefined) return syscall === exactSyscall
+  if (typeof path !== 'string' || path.length === 0 || path !== runnerProgram) return false
+  return syscall === 'spawn' || syscall === exactSyscall
+}
+
+/** Fatal runner evidence retained for infrastructure-error detail. */
+interface RunnerFailureMatch {
+  /** The original stderr line that matched a fatal signature. */
+  detail: string
 }

 /**
@@ -26,13 +69,37 @@ export function classifyDenial(result: BashRunResult, signatures: readonly strin
 }

 /**
- * Classify a failed run against the selected backend's runner-failure dialect.
- * @param result - settled foreground run.
- * @param signatures - case-insensitive runner-failure substrings from the active wrap.
- * @returns whether the failed run matches that runner-failure dialect.
+ * Classify one settled process against the selected backend's structured
+ * runner-failure rules. Each rule requires a nonzero exit, its optional
+ * exit-code gate, and a fatal signature on one stderr line after exact
+ * informational lines are excluded.
+ * @param exitCode - process exit code; null means signal termination.
+ * @param stderr - collected stderr text, left unchanged.
+ * @param rules - structured runner-failure rules from the active wrap.
+ * @returns the first matching fatal line, or undefined when evidence is insufficient.
 */
-export function classifyRunnerFailure(result: BashRunResult, signatures: readonly string[]): boolean {
-  return matchesSignature(result.exitCode, result.stderr.text, signatures)
+export function classifyRunnerFailure(
+  exitCode: number | null,
+  stderr: string,
+  rules: readonly RunnerFailureRule[],
+): RunnerFailureMatch | undefined {
+  if (exitCode === null || exitCode === 0) return undefined
+  const lines = stderr.split(/\r?\n/)
+  for (const rule of rules) {
+    if (rule.allowedExitCodes !== undefined && !rule.allowedExitCodes.includes(exitCode)) continue
+    const informationalLines = new Set((rule.informationalLines ?? []).map(line => line.toLowerCase()))
+    // An empty or whitespace-only substring is not meaningful runner evidence.
+    // Ignore it while keeping any valid signatures beside it active.
+    const fatalSignatures = rule.fatalSignatures
+      .filter(signature => signature.trim().length > 0)
+      .map(signature => signature.toLowerCase())
+    for (const line of lines) {
+      const lowered = line.toLowerCase()
+      if (informationalLines.has(lowered)) continue
+      if (fatalSignatures.some(signature => lowered.includes(signature))) return { detail: line }
+    }
+  }
+  return undefined
 }

 /**
--- a/packages/bash/bash-sandbox/src/index.ts
+++ b/packages/bash/bash-sandbox/src/index.ts
@@ -1,21 +1,29 @@
 /**
 * Sandbox-consuming bash executor. It wraps the exact local bash argv through
 * `ctx.sandbox`, inherits local process mechanics, and reports the selected
- * mode, enforcement, and denial facts. Runner failure means the command never
- * ran: foreground calls throw `SANDBOX_UNAVAILABLE`, while settled background
- * processes carry `runnerFailed`. The tool owns approval and passes a complete
- * per-call policy.
+ * mode, enforcement, and denial facts. Positive runner-launch evidence means
+ * the command never ran: foreground calls throw `SANDBOX_UNAVAILABLE`, while
+ * background processes carry `runnerFailed`; other spawn rejections retain
+ * local-executor semantics. The tool owns approval and passes a complete per-call policy.
 * @module @deepseek-ai/dsh-bash-sandbox
 */

 import { Context } from 'cordis'
 import type { BashExecRequest, BashExecSpec, BashProcess, BashRunResult } from '@deepseek-ai/dsh-bash'
 import { SandboxUnavailableError } from '@deepseek-ai/dsh-sandbox'
-import type { ConfinedSandboxMode, SandboxEnforcement, SandboxExecutionPolicy, SandboxMode, SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
+import type {
+  ConfinedArgv,
+  ConfinedSandboxMode,
+  RunnerFailureRule,
+  SandboxEnforcement,
+  SandboxExecutionPolicy,
+  SandboxMode,
+  SandboxPolicy,
+} from '@deepseek-ai/dsh-sandbox'
 import type {} from '@deepseek-ai/dsh-sandbox-policy'
 import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
 import type { Config as LocalConfig } from '@deepseek-ai/dsh-bash-local'
-import { classifyDenial, classifyRunnerFailure, matchesSignature, shellQuote } from './helpers.ts'
+import { classifyDenial, classifyRunnerFailure, isRunnerSpawnFailure, matchesSignature } from './helpers.ts'

 /**
 * Plugin config: the local executor's knobs, verbatim. The sandbox policy —
@@ -51,7 +59,9 @@ export class SandboxBashExecutor extends LocalBashExecutor {
    mode: ConfinedSandboxMode
    enforcement: SandboxEnforcement
    denialSignatures: readonly string[]
-    runnerFailureSignatures: readonly string[]
+    runnerFailureRules: readonly RunnerFailureRule[]
+    runnerProgram: string | undefined
+    workdir: string
  }>()

  constructor(ctx: Context, config: Config) {
@@ -83,11 +93,22 @@ export class SandboxBashExecutor extends LocalBashExecutor {
      return { ...result, sandbox: { mode, denied: false } }
    }
    const confined = this.confine(spec.command, { ...policy, mode })
-    const result = await super.run({ ...spec, command: confined.command })
-    // Runner failure outranks denial because the command did not run. Throw the
-    // same fail-closed error as confine-time discovery with the first stderr line.
-    if (classifyRunnerFailure(result, confined.runnerFailureSignatures)) {
-      throw new SandboxUnavailableError(mode, result.stderr.text.trim().split('\n')[0])
+    let result: BashRunResult
+    try {
+      result = await this.runArgv(spec, confined.argv)
+    } catch (error) {
+      // An upstream abort remains cancellation even when it prevents spawn.
+      if (spec.signal?.aborted === true) spec.signal.throwIfAborted()
+      if (isRunnerSpawnFailure(error, confined.argv[0], spec.workdir)) {
+        throw new SandboxUnavailableError(mode, String(error))
+      }
+      throw error
+    }
+    // Runner failure outranks denial because the command did not run. Carry
+    // the matched fatal line, not an informational line that preceded it.
+    const runnerFailure = classifyRunnerFailure(result.exitCode, result.stderr.text, confined.runnerFailureRules)
+    if (runnerFailure !== undefined) {
+      throw new SandboxUnavailableError(mode, runnerFailure.detail)
    }
    return { ...result, sandbox: { mode, denied: classifyDenial(result, confined.denialSignatures), enforcement: confined.enforcement } }
  }
@@ -96,11 +117,29 @@ export class SandboxBashExecutor extends LocalBashExecutor {
    const policy = spec.sandboxPolicy as SandboxExecutionPolicy
    const { mode } = policy
    if (mode === 'danger-full-access') return super.start(spec)
-    // Install facts synchronously; promise settlement cannot run before start() returns.
+    // Once startArgv returns, install facts synchronously; promise settlement
+    // cannot run before start() returns.
    const confined = this.confine(spec.command, { ...policy, mode })
-    const proc = super.start({ ...spec, command: confined.command })
-    const { enforcement, denialSignatures, runnerFailureSignatures } = confined
-    this.processFacts.set(proc, { mode, enforcement, denialSignatures, runnerFailureSignatures })
+    let proc: BashProcess
+    try {
+      proc = this.startArgv(spec, confined.argv)
+    } catch (error) {
+      // LocalSubprocessService reports provenanced ENOENT/EACCES through async
+      // `done` rejection; this covers alternatives that throw that shape synchronously.
+      if (isRunnerSpawnFailure(error, confined.argv[0], spec.workdir)) {
+        throw new SandboxUnavailableError(mode, String(error))
+      }
+      throw error
+    }
+    const { enforcement, denialSignatures, runnerFailureRules } = confined
+    this.processFacts.set(proc, {
+      mode,
+      enforcement,
+      denialSignatures,
+      runnerFailureRules,
+      runnerProgram: confined.argv[0],
+      workdir: spec.workdir,
+    })
    return proc
  }

@@ -108,12 +147,15 @@ export class SandboxBashExecutor extends LocalBashExecutor {
   * Stamp per-process sandbox facts before `done` settles. Full-access processes
   * have no facts; signal deaths are not denials.
   */
-  protected override onProcessDone(proc: BashProcess, stderr: string): void {
+  protected override onProcessDone(proc: BashProcess, stderr: string, spawnFailed: boolean, spawnError?: unknown): void {
    const facts = this.processFacts.get(proc)
    if (facts !== undefined) {
      this.processFacts.delete(proc)
-      // Runner failure outranks denial because its diagnostics may contain denial terms.
-      const runnerFailed = matchesSignature(proc.exitCode, stderr, facts.runnerFailureSignatures)
+      // A rejected spawn never started the confined launch. Otherwise runner
+      // failure outranks denial because its diagnostics may contain denial terms.
+      const runnerFailed = spawnFailed
+        ? isRunnerSpawnFailure(spawnError, facts.runnerProgram, facts.workdir)
+        : classifyRunnerFailure(proc.exitCode, stderr, facts.runnerFailureRules) !== undefined
      proc.sandbox = {
        mode: facts.mode,
        denied: !runnerFailed && matchesSignature(proc.exitCode, stderr, facts.denialSignatures),
@@ -121,30 +163,19 @@ export class SandboxBashExecutor extends LocalBashExecutor {
        ...(runnerFailed ? { runnerFailed } : {}),
      }
    }
-    super.onProcessDone(proc, stderr)
+    super.onProcessDone(proc, stderr, spawnFailed, spawnError)
  }

  /**
-   * Wrap one shell command via the `ctx.sandbox` provider: hand over the
-   * exact `['bash', '-c', command]` argv this executor would spawn, get back
-   * the confined argv, and re-assemble it into the `exec …` command string
-   * the inherited spawn path runs (the outer `bash -c` the subprocess service spawns
-   * `exec`s into the runner, so no extra shell lingers). Provider errors
-   * (fail-closed `SANDBOX_UNAVAILABLE`) propagate to the caller unchanged.
+   * Wrap one shell command via the `ctx.sandbox` provider. Provider errors
+   * propagate unchanged; the returned argv is handed directly to the local
+   * executor's subprocess path.
+   * @param command - shell source for the confined inner `bash -c`.
+   * @param policy - resolved confined execution policy.
+   * @returns the provider's exact argv and settlement-classification facts.
   */
-  private confine(command: string, policy: SandboxPolicy): {
-    command: string
-    enforcement: SandboxEnforcement
-    denialSignatures: readonly string[]
-    runnerFailureSignatures: readonly string[]
-  } {
-    const confined = this.ctx.sandbox.confine(['bash', '-c', command], policy)
-    return {
-      command: `exec ${confined.argv.map(shellQuote).join(' ')}`,
-      enforcement: confined.enforcement,
-      denialSignatures: confined.denialSignatures,
-      runnerFailureSignatures: confined.runnerFailureSignatures,
-    }
+  private confine(command: string, policy: SandboxPolicy): ConfinedArgv {
+    return this.ctx.sandbox.confine(['bash', '-c', command], policy)
  }
 }

--- a/packages/bash/bash-sandbox/tests/partial-landlock.spec.ts
+++ b/packages/bash/bash-sandbox/tests/partial-landlock.spec.ts
@@ -0,0 +1,270 @@
+/**
+ * Deterministic real-process proofs for runner classification: the real local
+ * provider and sandbox bash executor exercise direct runner-spawn failures
+ * and a POSIX fake Landlock launcher that prints its notice before exec.
+ */
+
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { LAUNCHER_FAILURE_EXIT } from 'node-addon-landlock-run'
+import { SANDBOX_UNAVAILABLE, SandboxUnavailableError } from '@deepseek-ai/dsh-sandbox'
+import { LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local'
+import { SandboxPolicyService } from '@deepseek-ai/dsh-sandbox-policy'
+import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox'
+import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
+
+const NOTICE = 'landlock-run: partial enforcement (older Landlock ABI)'
+const FATAL_PREFIX = 'landlock-run: '
+const FATAL = `${FATAL_PREFIX}landlock ruleset error: Invalid argument`
+
+const contexts: Context[] = []
+const tempDirs: string[] = []
+
+afterEach(async () => {
+  await Promise.all(contexts.splice(0).map(ctx => ctx.fiber.dispose()))
+  await Promise.all(tempDirs.splice(0).map(dir => rm(dir, { recursive: true, force: true })))
+})
+
+/** Write a fake native launcher that reports partial enforcement, then execs or fails. */
+async function fakeLauncher(fatalExit?: number): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'dsh-partial-landlock-'))
+  tempDirs.push(dir)
+  const launcher = join(dir, 'landlock-run')
+  const fatalBranch = fatalExit === undefined ? '' : `printf '%s\\n' '${FATAL}' >&2\nexit ${fatalExit}\n`
+  await writeFile(launcher, `#!/bin/sh
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --ro|--rw) shift 2 ;;
+    --) shift; break ;;
+    *) printf '%s\\n' '${FATAL_PREFIX}usage error: unexpected fake argument' >&2; exit ${LAUNCHER_FAILURE_EXIT} ;;
+  esac
+done
+printf '%s\\n' '${NOTICE}' >&2
+${fatalBranch}exec "$@"
+`, { mode: 0o755 })
+  return launcher
+}
+
+async function setup(fatalExit?: number): Promise<SandboxBashExecutor> {
+  const ctx = new Context()
+  contexts.push(ctx)
+  await ctx.plugin(LocalSandboxProvider, {})
+  const sandbox = ctx.sandbox as LocalSandboxProvider
+  sandbox.internals = {
+    platform: 'linux',
+    probeBwrap: () => false,
+    probeLandlock: () => 'partial',
+    landlockLauncher: await fakeLauncher(fatalExit),
+  }
+  await ctx.plugin(SandboxPolicyService, { mode: 'read-only', workspaceRoot: process.cwd() })
+  await ctx.plugin(LocalSubprocessService)
+  await ctx.plugin(SandboxBashExecutor, { cwd: process.cwd(), timeoutMs: 5_000 })
+  return ctx.bash as SandboxBashExecutor
+}
+
+async function setupConfiguredRunner(runner: string): Promise<SandboxBashExecutor> {
+  const ctx = new Context()
+  contexts.push(ctx)
+  await ctx.plugin(LocalSandboxProvider, {
+    runnerCommand: [runner],
+    runnerFailureSignatures: ['configured-runner: fatal'],
+  })
+  await ctx.plugin(SandboxPolicyService, { mode: 'read-only', workspaceRoot: process.cwd() })
+  await ctx.plugin(LocalSubprocessService)
+  await ctx.plugin(SandboxBashExecutor, { cwd: process.cwd(), timeoutMs: 5_000 })
+  return ctx.bash as SandboxBashExecutor
+}
+
+describe('partial Landlock runner-failure classification', () => {
+  it.each(['missing', 'unexecutable', 'missing-interpreter'] as const)('classifies a %s configured runner through the direct spawn error channel', async (kind) => {
+    const dir = await mkdtemp(join(tmpdir(), 'dsh-unusable-sandbox-runner-'))
+    tempDirs.push(dir)
+    const runner = join(dir, `${kind}-runner`)
+    if (kind === 'unexecutable') await writeFile(runner, '#!/bin/sh\nexit 0\n', { mode: 0o644 })
+    if (kind === 'missing-interpreter') {
+      await writeFile(runner, '#!/dsh-definitely-missing-sandbox-interpreter\nexit 0\n', { mode: 0o755 })
+    }
+    const bash = await setupConfiguredRunner(runner)
+
+    const error = await bash.run(bash.resolve({ command: 'true' })).catch((value: unknown) => value)
+    expect(error).toMatchObject({ name: 'SandboxUnavailableError', code: SANDBOX_UNAVAILABLE })
+    expect(error).toBeInstanceOf(Error)
+    expect((error as Error).message).toContain(runner)
+
+    const task = bash.start(bash.resolve({ command: 'true' }))
+    await task.done
+    expect(task.status).toBe('killed')
+    expect(task.readOutput().delta).toContain(`spawn failed: Error: spawn ${runner}`)
+    expect(task.sandbox).toEqual({
+      mode: 'read-only',
+      denied: false,
+      enforcement: 'full',
+      runnerFailed: true,
+    })
+    const accounting = (bash as unknown as { processFacts: Map<unknown, unknown> }).processFacts
+    expect(accounting.size).toBe(0)
+  })
+
+  it.each(['bare-name', 'relative'] as const)(
+    'classifies a %s runner whose shebang interpreter is missing',
+    async (form) => {
+      const dir = await mkdtemp(join(tmpdir(), 'dsh-argv-form-sandbox-runner-'))
+      tempDirs.push(dir)
+      const filename = 'missing-interpreter-runner'
+      const runner = form === 'bare-name' ? filename : `./${filename}`
+      await writeFile(join(dir, filename), '#!/dsh-definitely-missing-sandbox-interpreter\nexit 0\n', { mode: 0o755 })
+      const bash = await setupConfiguredRunner(runner)
+      const request = form === 'bare-name'
+        ? { command: 'true', env: { PATH: dir } }
+        : { command: 'true', workdir: dir }
+
+      const error = await bash.run(bash.resolve(request)).catch((value: unknown) => value)
+      expect(error).toMatchObject({ name: 'SandboxUnavailableError', code: SANDBOX_UNAVAILABLE })
+      expect(error).toBeInstanceOf(Error)
+      // Empirically, Darwin and Linux Node 24 preserve the passed bare/relative
+      // argv[0] in this spawn error rather than resolving it to an absolute path.
+      expect((error as Error).message).toContain(`spawn ${runner} ENOENT`)
+
+      const task = bash.start(bash.resolve(request))
+      await task.done
+      expect(task.status).toBe('killed')
+      expect(task.readOutput().delta).toContain(`spawn failed: Error: spawn ${runner} ENOENT`)
+      expect(task.sandbox).toEqual({
+        mode: 'read-only',
+        denied: false,
+        enforcement: 'full',
+        runnerFailed: true,
+      })
+    },
+  )
+
+  it('keeps a real malformed executable ordinary across no-shebang spawn behavior', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'dsh-malformed-sandbox-runner-'))
+    tempDirs.push(dir)
+    const runner = join(dir, 'malformed-runner')
+    await writeFile(runner, 'not a native executable or shebang script\n', { mode: 0o755 })
+    const bash = await setupConfiguredRunner(runner)
+    const request = { command: 'true' }
+
+    // Node/libuv may expose execve's ENOEXEC directly (Darwin) or retry a
+    // no-shebang executable through /bin/sh (Linux). Neither path supplies the
+    // provenanced ENOENT/EACCES evidence required for runner attribution.
+    const foreground = await bash.run(bash.resolve(request)).catch((value: unknown) => value)
+    expect(foreground).not.toBeInstanceOf(SandboxUnavailableError)
+
+    if (foreground instanceof Error) {
+      expect(foreground).toMatchObject({ code: 'ENOEXEC', syscall: 'spawn' })
+      expect((foreground as { path?: unknown }).path).toBeUndefined()
+
+      let background: unknown
+      try {
+        bash.start(bash.resolve(request))
+      } catch (error) {
+        background = error
+      }
+      expect(background).toMatchObject({ code: 'ENOEXEC', syscall: 'spawn' })
+      expect((background as { path?: unknown }).path).toBeUndefined()
+      expect(background).not.toBeInstanceOf(SandboxUnavailableError)
+    } else {
+      expect(foreground).toMatchObject({
+        exitCode: 127,
+        signal: null,
+        sandbox: { mode: 'read-only', denied: false, enforcement: 'full' },
+      })
+      expect((foreground as { stderr: { text: string } }).stderr.text.length).toBeGreaterThan(0)
+
+      const background = bash.start(bash.resolve(request))
+      await background.done
+      expect(background.status).toBe('completed')
+      expect(background.exitCode).toBe(127)
+      expect(background.signal).toBeNull()
+      expect(background.sandbox).toEqual({ mode: 'read-only', denied: false, enforcement: 'full' })
+      const output = background.readOutput().delta
+      expect(output.startsWith('[stderr]\n')).toBe(true)
+      expect(output.length).toBeGreaterThan('[stderr]\n'.length)
+      expect(output).not.toContain('spawn failed:')
+    }
+
+    const accounting = (bash as unknown as { processFacts: Map<unknown, unknown> }).processFacts
+    expect(accounting.size).toBe(0)
+  })
+
+  it.each([0, 1, 2, LAUNCHER_FAILURE_EXIT])(
+    'keeps child exit %i ordinary when the partial-enforcement notice is the only runner line',
+    async (exitCode) => {
+      const bash = await setup()
+      const result = await bash.run(bash.resolve({ command: `exit ${exitCode}` }))
+      expect(result.exitCode).toBe(exitCode)
+      expect(result.stderr.text).toBe(`${NOTICE}\n`)
+      expect(result.sandbox).toEqual({ mode: 'read-only', denied: false, enforcement: 'partial' })
+    },
+  )
+
+  it.each([126, 127])('keeps a successfully launched Landlock child exit %i as an ordinary outcome', async (exitCode) => {
+    const bash = await setup()
+    const result = await bash.run(bash.resolve({ command: `exit ${exitCode}` }))
+    expect(result.exitCode).toBe(exitCode)
+    expect(result.stderr.text).toBe(`${NOTICE}\n`)
+    expect(result.sandbox).toEqual({ mode: 'read-only', denied: false, enforcement: 'partial' })
+  })
+
+  it.each([1, 2])('keeps a Landlock fatal line at exit %i as insufficient runner-failure evidence', async (exitCode) => {
+    const bash = await setup(exitCode)
+    const result = await bash.run(bash.resolve({ command: 'true' }))
+    expect(result.exitCode).toBe(exitCode)
+    expect(result.stderr.text).toBe(`${NOTICE}\n${FATAL}\n`)
+    expect(result.sandbox).toEqual({ mode: 'read-only', denied: false, enforcement: 'partial' })
+  })
+
+  it('reports the fatal line after the notice as SANDBOX_UNAVAILABLE detail', async () => {
+    const bash = await setup(LAUNCHER_FAILURE_EXIT)
+    const error = await bash.run(bash.resolve({ command: 'true' })).catch((value: unknown) => value)
+    expect(error).toMatchObject({ name: 'SandboxUnavailableError', code: SANDBOX_UNAVAILABLE })
+    expect(error).toBeInstanceOf(Error)
+    expect((error as Error).message).toContain(`Runner failure: ${FATAL}`)
+    expect((error as Error).message).not.toContain(NOTICE)
+  })
+
+  it('classifies a notice plus child Permission denied as a denial, not runner failure', async () => {
+    const bash = await setup()
+    const result = await bash.run(bash.resolve({ command: 'printf "%s\\n" "child: Permission denied" >&2; exit 1' }))
+    expect(result.stderr.text).toBe(`${NOTICE}\nchild: Permission denied\n`)
+    expect(result.sandbox).toEqual({ mode: 'read-only', denied: true, enforcement: 'partial' })
+  })
+
+  it('applies the same evidence rule to notice-only background exits', async () => {
+    const bash = await setup()
+    for (const command of ['exit 1', 'exit 2', `exit ${LAUNCHER_FAILURE_EXIT}`]) {
+      const task = bash.start(bash.resolve({ command }))
+      await task.done
+      expect(task.sandbox).toEqual({ mode: 'read-only', denied: false, enforcement: 'partial' })
+      expect(task.readOutput().delta).toContain(NOTICE)
+    }
+  })
+
+  it('classifies a background notice plus child Permission denied as denial', async () => {
+    const bash = await setup()
+    const task = bash.start(bash.resolve({ command: 'printf "%s\\n" "child: Permission denied" >&2; exit 1' }))
+    await task.done
+    expect(task.sandbox).toEqual({ mode: 'read-only', denied: true, enforcement: 'partial' })
+    expect(task.readOutput().delta).toContain(NOTICE)
+  })
+
+  it('makes a background fatal line outrank denial text after the notice', async () => {
+    const bash = await setup(LAUNCHER_FAILURE_EXIT)
+    const task = bash.start(bash.resolve({ command: 'true' }))
+    await task.done
+    expect(task.sandbox).toEqual({
+      mode: 'read-only',
+      denied: false,
+      enforcement: 'partial',
+      runnerFailed: true,
+    })
+    const output = task.readOutput().delta
+    expect(output).toContain(NOTICE)
+    expect(output).toContain(FATAL)
+  })
+})
--- a/packages/bash/bash-sandbox/tests/sandbox.spec.ts
+++ b/packages/bash/bash-sandbox/tests/sandbox.spec.ts
@@ -5,7 +5,7 @@
 * the Unix denial signature used by the classifier without requiring a real sandbox runner.
 */

-import { chmodSync, mkdirSync, mkdtempSync } from 'node:fs'
+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join, resolve } from 'node:path'
 import { describe, expect, it, vi } from 'vitest'
@@ -16,7 +16,8 @@ import type { ConfinedArgv, SandboxExecutionPolicy, SandboxMode, SandboxPolicy }
 import { SandboxPolicyService } from '@deepseek-ai/dsh-sandbox-policy'
 import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox'
 import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
-import { classifyDenial, classifyRunnerFailure, shellQuote } from '../src/helpers.ts'
+import type { SubprocessHandle, SubprocessOutputReader } from '@deepseek-ai/dsh-subprocess'
+import { classifyDenial, classifyRunnerFailure, isRunnerSpawnFailure } from '../src/helpers.ts'
 import type { Config } from '@deepseek-ai/dsh-bash-sandbox'

 const spillDir = mkdtempSync(join(tmpdir(), 'dsh-bash-sandbox-spec-'))
@@ -30,12 +31,19 @@ interface ConfineCall {
 /** The Linux file-denial dialects the fake wraps carry — matches the unix-permission denials the tests below produce. */
 const UNIX_SIGNATURES = ['read-only file system', 'permission denied'] as const

-/** The runner-failure prefix the fake wraps carry (a fake-runner: error line marks the sandbox itself failing). */
-const RUNNER_FAILURE = ['fake-runner: '] as const
+/** The runner-failure rule the fake wraps carry (a fake-runner: error line marks the sandbox itself failing). */
+const RUNNER_FAILURE = [{ fatalSignatures: ['fake-runner: '] }] as const
+
+/** Provider argv[0] forms that all share the caller-owned cwd spawn precondition. */
+const RUNNER_FORMS = [
+  ['absolute', process.execPath],
+  ['bare', 'node'],
+  ['relative', './sandbox-runner'],
+] as const

 /** A passthrough wrap: the caller's argv unchanged, asserted full — commands run unconfined, deterministically. */
 const passthrough = (argv: readonly string[]): ConfinedArgv =>
-  ({ argv: [...argv], enforcement: 'full', denialSignatures: UNIX_SIGNATURES, runnerFailureSignatures: RUNNER_FAILURE })
+  ({ argv: [...argv], enforcement: 'full', denialSignatures: UNIX_SIGNATURES, runnerFailureRules: RUNNER_FAILURE })

 /**
 * Boot a context with a recording fake `ctx.sandbox` (behavior injectable
@@ -90,15 +98,49 @@ describe('the provider hand-off', () => {
    }])
  })

-  it('a wrapped argv from the provider is what actually spawns (prefix survives, quoting round-trips)', async () => {
-    // The fake wraps with `env MARKER=...` — a real (if tiny) runner prefix:
-    // the sentinel only prints if the executor spawned the WRAPPED argv.
-    const { bash } = await setup({}, argv => ({ argv: ['env', 'DSH_WRAP=1', ...argv], enforcement: 'full', denialSignatures: UNIX_SIGNATURES, runnerFailureSignatures: RUNNER_FAILURE }))
+  it('hands the provider\'s returned argv directly to ctx.subprocess.spawn', async () => {
+    const returnedArgv = ['env', 'DSH_WRAP=1', 'bash', '-c', 'printf "%s" "$DSH_WRAP"']
+    const { ctx, bash } = await setup({}, () => ({ argv: returnedArgv, enforcement: 'full', denialSignatures: UNIX_SIGNATURES, runnerFailureRules: RUNNER_FAILURE }))
+    const spawn = vi.spyOn(ctx.subprocess, 'spawn')
    const result = await bash.run(bash.resolve({ command: 'printf "%s" "$DSH_WRAP"' }))
    expect(result.stdout.text).toBe('1')
+    expect(spawn).toHaveBeenCalledTimes(1)
+    expect(spawn.mock.calls[0]?.[0].argv).toEqual(returnedArgv)
    expect(result.sandbox).toEqual({ mode: 'read-only', denied: false, enforcement: 'full' })
  })

+  it('starts a non-Bash runner before the confined inner Bash evaluates BASH_ENV', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'dsh-bash-env-order-'))
+    const hook = join(dir, 'hook.sh')
+    const order = join(dir, 'order.txt')
+    writeFileSync(hook, 'printf "hook\\n" >> "$DSH_ORDER_FILE"\n')
+    const runnerScript = [
+      'const { appendFileSync } = require("node:fs");',
+      'const { spawnSync } = require("node:child_process");',
+      'appendFileSync(process.env.DSH_ORDER_FILE, "runner\\n");',
+      'const child = spawnSync(process.argv[1], process.argv.slice(2), { env: process.env, stdio: "inherit" });',
+      'process.exit(child.status ?? 125);',
+    ].join('')
+    const { bash } = await setup({}, argv => ({
+      argv: [process.execPath, '-e', runnerScript, ...argv],
+      enforcement: 'full',
+      denialSignatures: UNIX_SIGNATURES,
+      runnerFailureRules: RUNNER_FAILURE,
+    }))
+
+    try {
+      const result = await bash.run(bash.resolve({
+        command: 'true',
+        env: { BASH_ENV: hook },
+        dshEnv: { DSH_ORDER_FILE: order },
+      }))
+      expect(result.exitCode).toBe(0)
+      expect(readFileSync(order, 'utf8')).toBe('runner\nhook\n')
+    } finally {
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
  it('workspace-write rides the policy, workspaceRoot falling back to process.cwd() when not configured', async () => {
    const { bash, calls } = await setup({ mode: 'workspace-write' })
    const result = await bash.run(bash.resolve({ command: 'true' }))
@@ -120,9 +162,6 @@ describe('the provider hand-off', () => {
    expect(calls).toHaveLength(2)
  })

-  it('shellQuote survives embedded single quotes (the argv re-assembly primitive)', () => {
-    expect(shellQuote('a\'b')).toBe(String.raw`'a'\''b'`)
-  })
 })

 describe('fail closed', () => {
@@ -132,6 +171,120 @@ describe('fail closed', () => {
    await expect(bash.run(spec)).rejects.toMatchObject({ name: 'SandboxUnavailableError', code: SANDBOX_UNAVAILABLE })
    expect(() => bash.start(spec)).toThrow(SandboxUnavailableError)
  })
+
+  it('preserves an already-aborted foreground call as cancellation', async () => {
+    const { bash } = await setup()
+    const controller = new AbortController()
+    const reason = new Error('caller cancelled before spawn')
+    controller.abort(reason)
+    await expect(bash.run(bash.resolve({ command: 'true', signal: controller.signal }))).rejects.toBe(reason)
+  })
+
+  it.each(RUNNER_FORMS)(
+    'keeps an invalid workdir ordinary with the %s provider-runner form',
+    async (_form, runner) => {
+      const { bash } = await setup({}, argv => ({
+        argv: [runner, ...argv],
+        enforcement: 'full',
+        denialSignatures: UNIX_SIGNATURES,
+        runnerFailureRules: RUNNER_FAILURE,
+      }))
+      const parent = mkdtempSync(join(tmpdir(), 'dsh-sandbox-missing-cwd-'))
+      try {
+        const failure = await bash.run(bash.resolve({ command: 'true', workdir: join(parent, 'missing') }))
+          .catch((error: unknown) => error)
+        expect(failure).toMatchObject({ code: 'ENOENT' })
+        expect(failure).not.toBeInstanceOf(SandboxUnavailableError)
+      } finally {
+        rmSync(parent, { recursive: true, force: true })
+      }
+    },
+  )
+
+  it('keeps an invalid workdir ordinary when danger-full-access bypasses the provider', async () => {
+    const { bash } = await setup({ mode: 'danger-full-access' })
+    const parent = mkdtempSync(join(tmpdir(), 'dsh-sandbox-missing-cwd-'))
+    try {
+      const failure = await bash.run(bash.resolve({ command: 'true', workdir: join(parent, 'missing') }))
+        .catch((error: unknown) => error)
+      expect(failure).toMatchObject({ code: 'ENOENT' })
+      expect(failure).not.toBeInstanceOf(SandboxUnavailableError)
+    } finally {
+      rmSync(parent, { recursive: true, force: true })
+    }
+  })
+
+  it('keeps Node-shaped synchronous ENOEXEC ordinary in run() and start()', async () => {
+    const runner = join(spillDir, 'malformed-runner')
+    const { ctx, bash } = await setup({}, argv => ({
+      argv: [runner, ...argv],
+      enforcement: 'full',
+      denialSignatures: UNIX_SIGNATURES,
+      runnerFailureRules: RUNNER_FAILURE,
+    }))
+    vi.spyOn(ctx.subprocess, 'spawn').mockImplementation(() => {
+      throw Object.assign(new Error('spawn ENOEXEC'), { code: 'ENOEXEC', syscall: 'spawn' })
+    })
+
+    const foreground = await bash.run(bash.resolve({ command: 'true' })).catch((error: unknown) => error)
+    expect(foreground).toMatchObject({ code: 'ENOEXEC', syscall: 'spawn' })
+    expect(foreground).not.toBeInstanceOf(SandboxUnavailableError)
+
+    let background: unknown
+    try {
+      bash.start(bash.resolve({ command: 'true' }))
+    } catch (error) {
+      background = error
+    }
+    expect(background).toMatchObject({ code: 'ENOEXEC', syscall: 'spawn' })
+    expect(background).not.toBeInstanceOf(SandboxUnavailableError)
+  })
+
+  it('classifies a synchronous SubprocessService EACCES with exact runner provenance', async () => {
+    const runner = join(spillDir, 'unexecutable-runner')
+    const { ctx, bash } = await setup({}, argv => ({
+      argv: [runner, ...argv],
+      enforcement: 'full',
+      denialSignatures: UNIX_SIGNATURES,
+      runnerFailureRules: RUNNER_FAILURE,
+    }))
+    // This pins an alternative SubprocessService's synchronous seam, not the
+    // shipped local behavior.
+    vi.spyOn(ctx.subprocess, 'spawn').mockImplementation(() => {
+      throw Object.assign(new Error('spawn EACCES'), { code: 'EACCES', syscall: 'spawn', path: runner })
+    })
+
+    await expect(bash.run(bash.resolve({ command: 'true' })))
+      .rejects.toMatchObject({ name: 'SandboxUnavailableError', code: SANDBOX_UNAVAILABLE })
+    expect(() => bash.start(bash.resolve({ command: 'true' })))
+      .toThrow(expect.objectContaining({ name: 'SandboxUnavailableError', code: SANDBOX_UNAVAILABLE }))
+  })
+
+  it('keeps a synchronous cwd-owned ENOENT as the original start() error', async () => {
+    const runner = './sandbox-runner'
+    const { ctx, bash } = await setup({}, argv => ({
+      argv: [runner, ...argv],
+      enforcement: 'full',
+      denialSignatures: UNIX_SIGNATURES,
+      runnerFailureRules: RUNNER_FAILURE,
+    }))
+    const parent = mkdtempSync(join(tmpdir(), 'dsh-sandbox-missing-cwd-'))
+    const workdir = join(parent, 'missing')
+    const failure = Object.assign(new Error('spawn ENOENT'), { code: 'ENOENT', syscall: `spawn ${runner}`, path: runner })
+    vi.spyOn(ctx.subprocess, 'spawn').mockImplementation(() => { throw failure })
+    try {
+      let thrown: unknown
+      try {
+        bash.start(bash.resolve({ command: 'true', workdir }))
+      } catch (error) {
+        thrown = error
+      }
+      expect(thrown).toBe(failure)
+      expect(thrown).not.toBeInstanceOf(SandboxUnavailableError)
+    } finally {
+      rmSync(parent, { recursive: true, force: true })
+    }
+  })
 })

 describe('danger-full-access', () => {
@@ -233,15 +386,134 @@ describe('classifyDenial', () => {
  })
 })

+describe('isRunnerSpawnFailure', () => {
+  it.each(['EACCES', 'ENOENT'])(
+    'attributes executable-class spawn code %s to argv[0] once cwd ambiguity is eliminated',
+    (code) => {
+      const runner = join(spillDir, 'runner')
+      const error = Object.assign(new Error('spawn failed'), { code, syscall: `spawn ${runner}`, path: runner })
+      expect(isRunnerSpawnFailure(error, runner, process.cwd())).toBe(true)
+    },
+  )
+
+  it.each(['ENOEXEC', 'ENOTDIR', 'EPERM'])(
+    'keeps unproven executable code %s ordinary despite synthetic argv[0] fields',
+    (code) => {
+      const runner = join(spillDir, 'runner')
+      const error = Object.assign(new Error('spawn failed'), { code, syscall: `spawn ${runner}`, path: runner })
+      expect(isRunnerSpawnFailure(error, runner, process.cwd())).toBe(false)
+    },
+  )
+
+  it('requires a usable caller cwd before classifying absolute, bare, or relative runners', () => {
+    const missingWorkdir = join(spillDir, 'missing-workdir')
+    for (const [, runner] of RUNNER_FORMS) {
+      const error = Object.assign(new Error('spawn failed'), { code: 'ENOENT', syscall: `spawn ${runner}`, path: runner })
+      expect(isRunnerSpawnFailure(error, runner, missingWorkdir)).toBe(false)
+    }
+    const fileWorkdir = join(spillDir, 'not-a-workdir')
+    writeFileSync(fileWorkdir, '')
+    const error = Object.assign(new Error('spawn failed'), { code: 'ENOTDIR', syscall: 'spawn node', path: 'node' })
+    expect(isRunnerSpawnFailure(error, 'node', fileWorkdir)).toBe(false)
+  })
+
+  it('rejects resource, non-spawn, mismatched-program, and unstructured failures', () => {
+    const missingRunner = join(spillDir, 'definitely-missing-runner')
+    const spawnError = (code: unknown, syscall: unknown = `spawn ${missingRunner}`, path: unknown = missingRunner) =>
+      Object.assign(new Error('spawn failed'), { code, syscall, path })
+    const spawnErrorWithoutPath = (syscall: string) =>
+      Object.assign(new Error('spawn failed'), { code: 'ENOENT', syscall })
+
+    expect(isRunnerSpawnFailure(spawnError('EMFILE'), missingRunner, process.cwd())).toBe(false)
+    expect(isRunnerSpawnFailure(spawnError('ENOMEM'), missingRunner, process.cwd())).toBe(false)
+    expect(isRunnerSpawnFailure(spawnError(2), missingRunner, process.cwd())).toBe(false)
+    expect(isRunnerSpawnFailure(spawnError('ENOENT', 'open'), missingRunner, process.cwd())).toBe(false)
+    expect(isRunnerSpawnFailure(spawnError('ENOENT', 1), missingRunner, process.cwd())).toBe(false)
+    expect(isRunnerSpawnFailure(spawnError('ENOENT', 'spawn', process.execPath), missingRunner, process.cwd())).toBe(false)
+    expect(isRunnerSpawnFailure(spawnError('ENOENT', 'spawn', 1), missingRunner, process.cwd())).toBe(false)
+    expect(isRunnerSpawnFailure(spawnError('ENOENT', 'spawn', ''), missingRunner, process.cwd())).toBe(false)
+    expect(isRunnerSpawnFailure(spawnErrorWithoutPath('spawn'), missingRunner, process.cwd())).toBe(false)
+    expect(isRunnerSpawnFailure(spawnErrorWithoutPath('spawn other-runner'), missingRunner, process.cwd())).toBe(false)
+    expect(isRunnerSpawnFailure(undefined, missingRunner, process.cwd())).toBe(false)
+    expect(isRunnerSpawnFailure(null, missingRunner, process.cwd())).toBe(false)
+    expect(isRunnerSpawnFailure(spawnError('ENOENT'), undefined, process.cwd())).toBe(false)
+  })
+
+  it('accepts only syscall provenance compatible with the exact runner program', () => {
+    const runner = join(spillDir, 'runner with spaces')
+    const spawnError = (syscall: string, path?: string) =>
+      Object.assign(new Error('spawn failed'), { code: 'ENOENT', syscall, path })
+
+    expect(isRunnerSpawnFailure(spawnError('spawn', runner), runner, process.cwd())).toBe(true)
+    expect(isRunnerSpawnFailure(spawnError(`spawn ${runner}`, runner), runner, process.cwd())).toBe(true)
+    expect(isRunnerSpawnFailure(spawnError(`spawn ${runner}`), runner, process.cwd())).toBe(true)
+    expect(isRunnerSpawnFailure(spawnError('spawn other-runner', runner), runner, process.cwd())).toBe(false)
+  })
+})
+
 describe('classifyRunnerFailure', () => {
-  it('matches the dialect case-insensitively on BOTH sides — the seam declares it so, and producers compose signatures from runtime data (an argv0 path, the shell\'s `No such file or directory`)', () => {
-    const signatures = ['exec: /Opt/Runners/bwrap: not found', '/Opt/Runners/bwrap: No such file or directory']
-    expect(classifyRunnerFailure(runResult(127, 'bash: /Opt/Runners/bwrap: No such file or directory'), signatures)).toBe(true)
-    expect(classifyRunnerFailure(runResult(127, 'BASH: LINE 1: EXEC: /OPT/RUNNERS/BWRAP: NOT FOUND'), signatures)).toBe(true)
+  it('ignores empty and whitespace-only fatal signatures instead of treating exit status or notice text as evidence', () => {
+    const notice = 'landlock-run: partial enforcement (older Landlock ABI)'
+    const emptyRule = [{ allowedExitCodes: [125], fatalSignatures: ['', ' ', '\t'] }]
+    expect(classifyRunnerFailure(125, '', emptyRule)).toBeUndefined()
+    expect(classifyRunnerFailure(125, notice, emptyRule)).toBeUndefined()
+  })
+
+  it('keeps valid fatal signatures active beside an ignored empty entry', () => {
+    const notice = 'landlock-run: partial enforcement (older Landlock ABI)'
+    const fatal = 'landlock-run: ruleset creation failed'
+    const rules = [{
+      allowedExitCodes: [125],
+      fatalSignatures: ['', ' ', 'landlock-run: '],
+      informationalLines: [notice],
+    }]
+    expect(classifyRunnerFailure(125, `${notice}\nchild diagnostic\n${fatal}`, rules)).toEqual({ detail: fatal })
+  })
+
+  it('requires Landlock exit 125 plus a non-notice fatal line and returns that original line', () => {
+    const notice = 'landlock-run: partial enforcement (older Landlock ABI)'
+    const rules = [{ allowedExitCodes: [125], fatalSignatures: ['landlock-run: '], informationalLines: [notice] }]
+    expect(classifyRunnerFailure(1, notice, rules)).toBeUndefined()
+    expect(classifyRunnerFailure(2, notice, rules)).toBeUndefined()
+    expect(classifyRunnerFailure(125, notice, rules)).toBeUndefined()
+    expect(classifyRunnerFailure(125, notice.toUpperCase(), rules)).toBeUndefined()
+    expect(classifyRunnerFailure(125, `${notice}: extra detail`, rules))
+      .toEqual({ detail: `${notice}: extra detail` })
+    expect(classifyRunnerFailure(125, `${notice}\nlandlock-run: exec failed: No such file or directory`, rules))
+      .toEqual({ detail: 'landlock-run: exec failed: No such file or directory' })
+  })
+
+  it.each([
+    'landlock-run: usage error: missing `-- <argv>...` command',
+    'landlock-run: landlock is not enforced by this kernel (ABI unsupported or disabled)',
+    'landlock-run: cannot open rule path: /gone: No such file or directory',
+    'landlock-run: landlock ruleset error: Invalid argument',
+    'landlock-run: exec failed: Permission denied',
+    'landlock-run: out of memory',
+    'landlock-run: future fatal diagnostic',
+  ])('keeps known and future Landlock fatal diagnostics fail-closed: %s', (fatal) => {
+    const rules = [{
+      allowedExitCodes: [125],
+      fatalSignatures: ['landlock-run: '],
+      informationalLines: ['landlock-run: partial enforcement (older Landlock ABI)'],
+    }]
+    expect(classifyRunnerFailure(125, fatal, rules)).toEqual({ detail: fatal })
  })
 })

 describe('result facts', () => {
+  it.each([126, 127])('keeps a successfully launched wrapped child exit %i as an ordinary outcome', async (exitCode) => {
+    const { bash } = await setup({}, argv => ({
+      argv: ['env', ...argv],
+      enforcement: 'full',
+      denialSignatures: UNIX_SIGNATURES,
+      runnerFailureRules: RUNNER_FAILURE,
+    }))
+    const result = await bash.run(bash.resolve({ command: `exit ${exitCode}` }))
+    expect(result.exitCode).toBe(exitCode)
+    expect(result.sandbox).toEqual({ mode: 'read-only', denied: false, enforcement: 'full' })
+  })
+
  it('reports a real permission failure as a sandbox denial with the mode it ran under', async () => {
    const { bash } = await setup()
    const lockedDir = join(mkdtempSync(join(tmpdir(), 'dsh-sandbox-denied-')), 'locked')
@@ -253,25 +525,66 @@ describe('result facts', () => {
  })

  it('carries the provider\'s partial-enforcement fact through unchanged', async () => {
-    const { bash } = await setup({}, argv => ({ argv: [...argv], enforcement: 'partial', denialSignatures: UNIX_SIGNATURES, runnerFailureSignatures: RUNNER_FAILURE }))
+    const { bash } = await setup({}, argv => ({ argv: [...argv], enforcement: 'partial', denialSignatures: UNIX_SIGNATURES, runnerFailureRules: RUNNER_FAILURE }))
    const result = await bash.run(bash.resolve({ command: 'true' }))
    expect(result.sandbox).toEqual({ mode: 'read-only', denied: false, enforcement: 'partial' })
  })
 })

 describe('background sandbox facts', () => {
-  it('stamps facts and releases accounting when background spawn fails', async () => {
-    const { bash } = await setup()
-    const missingWorkdir = join(mkdtempSync(join(tmpdir(), 'dsh-sandbox-missing-cwd-')), 'missing')
-    const task = bash.start(bash.resolve({ command: 'true', workdir: missingWorkdir }))
+  it.each(RUNNER_FORMS)('keeps an invalid-workdir rejection ordinary for the %s provider-runner form', async (_form, runner) => {
+    const { bash } = await setup({}, argv => ({
+      argv: [runner, ...argv],
+      enforcement: 'full',
+      denialSignatures: UNIX_SIGNATURES,
+      runnerFailureRules: RUNNER_FAILURE,
+    }))
+    const parent = mkdtempSync(join(tmpdir(), 'dsh-sandbox-missing-cwd-'))
+    try {
+      const task = bash.start(bash.resolve({ command: 'true', workdir: join(parent, 'missing') }))
+      await task.done

+      expect(task.status).toBe('killed')
+      expect(task.readOutput().delta).toContain('spawn failed:')
+      expect(task.sandbox).toEqual({
+        mode: 'read-only',
+        denied: false,
+        enforcement: 'full',
+      })
+      const accounting = (bash as unknown as { processFacts: Map<unknown, unknown> }).processFacts
+      expect(accounting.size).toBe(0)
+    } finally {
+      rmSync(parent, { recursive: true, force: true })
+    }
+  })
+
+  it('does not invent runner evidence when a spawn rejection has no structured reason', async () => {
+    const { ctx, bash } = await setup()
+    const emptyReader: SubprocessOutputReader = {
+      readFrom: () => ({ text: '', nextOffset: 0, lossy: false }),
+    }
+    vi.spyOn(ctx.subprocess, 'spawn').mockReturnValue({
+      pid: -1,
+      stdin: undefined,
+      stdout: undefined,
+      stderr: undefined,
+      collected: { stdout: emptyReader, stderr: emptyReader },
+      // Arbitrary subprocess providers can reject without a value; that edge is the point of this test.
+      // oxlint-disable-next-line typescript/prefer-promise-reject-errors
+      done: Promise.reject(undefined),
+      terminate: vi.fn(),
+      waitForExit: async () => true,
+    } satisfies SubprocessHandle)
+
+    const task = bash.start(bash.resolve({ command: 'true' }))
    await task.done

-    expect(task.status).toBe('killed')
-    expect(task.readOutput().delta).toContain('spawn failed:')
-    expect(task.sandbox).toEqual({ mode: 'read-only', denied: false, enforcement: 'full' })
-    const accounting = (bash as unknown as { processFacts: Map<unknown, unknown> }).processFacts
-    expect(accounting.size).toBe(0)
+    expect(task.readOutput().delta).toContain('spawn failed: undefined')
+    expect(task.sandbox).toEqual({
+      mode: 'read-only',
+      denied: false,
+      enforcement: 'full',
+    })
  })

  it('stamps a settled denial: nonzero exit + permission stderr under a confined mode', async () => {
@@ -284,7 +597,7 @@ describe('background sandbox facts', () => {
  it('a foreground runner failure throws the fail-closed error, never a task result', async () => {
    // The wrap's runner prefix on a failed run means the SANDBOX broke and
    // the command never ran — the late twin of the confine-time throw, with
-    // the runner's own first stderr line carried as the cause.
+    // the matched fatal stderr line carried as the cause.
    const { bash } = await setup()
    const run = bash.run(bash.resolve({ command: 'echo "fake-runner: ruleset rejected" >&2; exit 125' }))
    await expect(run).rejects.toThrow(expect.objectContaining({ code: SANDBOX_UNAVAILABLE }))
@@ -315,7 +628,7 @@ describe('background sandbox facts', () => {
    let call = 0
    const { bash } = await setup({}, (argv) => {
      const wrap = wraps[Math.min(call++, wraps.length - 1)] as Pick<ConfinedArgv, 'enforcement' | 'denialSignatures'>
-      return { argv: [...argv], ...wrap, runnerFailureSignatures: RUNNER_FAILURE }
+      return { argv: [...argv], ...wrap, runnerFailureRules: RUNNER_FAILURE }
    })
    const slow = bash.start(bash.resolve({ command: 'sleep 0.4; echo "x: Permission denied" >&2; exit 1' }))
    const quick = bash.start(bash.resolve({ command: 'true' }))
--- a/packages/bash/bash-sandbox/tests/seatbelt.e2e.ts
+++ b/packages/bash/bash-sandbox/tests/seatbelt.e2e.ts
@@ -1,6 +1,6 @@
 import { spawnSync } from 'node:child_process'
 import { existsSync, readFileSync } from 'node:fs'
-import { mkdtemp, rm } from 'node:fs/promises'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
@@ -76,6 +76,32 @@ describe.skipIf(!seatbeltUsable)('bash-sandbox: real Seatbelt confinement throug
    expect(existsSync(join(outside, 'denied.txt'))).toBe(false)
  })

+  it('evaluates BASH_ENV only after Seatbelt confines the inner Bash', async () => {
+    const workdir = await tempDir(homedir())
+    const outside = await tempDir(homedir())
+    const hook = join(workdir, 'bash-env-hook.sh')
+    const insideProbe = join(workdir, 'hook-ran.txt')
+    const outsideProbe = join(outside, 'escaped.txt')
+    await writeFile(hook, [
+      'printf hook > "$DSH_BASH_ENV_INSIDE"',
+      'printf escaped > "$DSH_BASH_ENV_OUTSIDE"',
+      '',
+    ].join('\n'))
+    const bash = await sandboxedBash(workdir, 'workspace-write')
+
+    await bash.run(bash.resolve({
+      command: 'true',
+      env: { BASH_ENV: hook },
+      dshEnv: {
+        DSH_BASH_ENV_INSIDE: insideProbe,
+        DSH_BASH_ENV_OUTSIDE: outsideProbe,
+      },
+    }))
+
+    expect(readFileSync(insideProbe, 'utf8')).toBe('hook')
+    expect(existsSync(outsideProbe)).toBe(false)
+  })
+
  it('classifies a background denial once the task settles', async () => {
    const workdir = await tempDir(homedir())
    const bash = await sandboxedBash(workdir, 'read-only')
--- a/packages/bash/bash/README.i18n.yaml
+++ b/packages/bash/bash/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/bash/bash/README.md
-README.md: d7bf746969f52000fe298b65b995b7c631d8001c
-README.zh.md: a7c0cac0bce2154362c822c213a44f3c507d541c
+README.md: 88f519a21a0889d6b7649502c51077940c23709f
+README.zh.md: 294044692133da8baa57583146352e84c1ff9946
--- a/packages/bash/bash/README.md
+++ b/packages/bash/bash/README.md
@@ -25,7 +25,7 @@ The split mirrors the LLM seam (`LlmService`/`LlmAdapter`) and the agent-tool su
 | `BashProcess.readOutput()` | **Incremental** output read — consecutive reads never re-deliver. Reads that lost data to buffer bounds flag `lossy` and point at full-stream spill files. |
 | `BashProcess.kill()` | Kill the process group. Returns `false` when it already finished. |

-Implementations subclass `BashExecutor` and implement the abstract methods. Disposal must kill every running process and await its exit — see the HMR-safety tests.
+Implementations subclass `BashExecutor` and implement the abstract methods. Disposal must kill every running process and await its exit.

 ## Vocabulary

@@ -35,6 +35,8 @@ The per-session sandbox-mode override vocabulary (the `'sandbox/mode'` event, th

 `stdin` and ordinary `env` are set by in-process plugins (the hooks bridges, native plugins) to feed a hook command its JSON payload and `CLAUDE_PROJECT_DIR`/`CLAUDE_PLUGIN_ROOT` values. `dshEnv` is a separate trusted overlay restricted by type to managed keys; the exported `DSH_ENV_PREFIX` is the single source for that namespace, its `DshEnvironmentKey` template type, executor scrubbing, registry validation, derived built-in names, and model guidance. Model bash uses the current snapshot collected by `ctx.bashEnv`. Implementations remove inherited managed keys, then merge `dshEnv` after ordinary `env`, so an omitted current fact cannot fall back to stale ambient state and an `env` entry cannot displace a managed value. The model-facing tool exposes none of these as parameters. All three remain optional on the resolved spec; absent means no input/overlay. See [the bash-stdin-env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) and [the session environment Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md).

+The exported `parseExitStatus` (with `ParsedExitStatus`) is the shared rendering contract half of the shell tools: the inverse of the `[exit code: N]` / `[killed by signal: X]` markers `dsh-tool-bash`'s `renderResult` and `dsh-tool-pwsh`'s `renderPwshResult` append. Both tools' `presentResult` use it to split the rendered text into the terminal card's output body and its exit-status pill; it lives on the seam so the two tools never drift on the marker contract.
+
 ## Model Experience

 Indirectly, through `dsh-tool-bash`, which turns executor output and sandbox facts into guidance and retained tool-result tokens.
--- a/packages/bash/bash/README.zh.md
+++ b/packages/bash/bash/README.zh.md
@@ -4,7 +4,7 @@

 **bash 执行器 seam**：抽象 `BashExecutor` 服务（`ctx.bash`）定义 bash 后端做什么，即运行前台命令与启动后台进程，但不规定如何实现。task id、所有权、收集、取消与通知属于通用 `ctx.tasks` 运行时。

-本包（package）是 bash 能力中负责接口的四分之一，各项职责因此可以独立演进（和替换）：
+本包是 bash 能力中负责接口的四分之一，各项职责因此可以独立演进（和替换）：

 | 包 | 职责 |
 |---|---|
@@ -25,7 +25,7 @@
 | `BashProcess.readOutput()` | **增量** 读取输出：连续读取绝不会重复交付。因缓冲区边界丢失数据的读取会标记 `lossy`，并指向完整流 spill 文件。 |
 | `BashProcess.kill()` | 终止进程组。如果进程已结束，返回 `false`。 |

-实现会继承 `BashExecutor` 并实现抽象方法。dispose（资源释放）必须终止每个运行中的进程并等待其退出，详见 HMR（热模块替换）安全测试。
+实现会继承 `BashExecutor` 并实现抽象方法。dispose（资源释放）必须终止每个运行中的进程并等待其退出。

 ## 词汇

@@ -33,7 +33,9 @@

 每会话沙箱模式覆盖词汇（`'sandbox/mode'` 事件、`effectiveSandboxMode(events)` fold 以及 `setSandboxMode(session, mode)` 写入路径）不位于此处。它是所有强制执行家族共享的策略状态，属于 [`@deepseek-ai/dsh-sandbox-policy`](../../sandbox/sandbox-policy/)。`run()` 返回 `BashRunResult`；`start()` 返回 `BashProcess`，其增量读取与终止方法由 `dsh-tool-bash` 适配为通用任务注册。沙箱执行器会在前台结果与已结算进程句柄上标记 `BashSandboxInfo`。详见 `src/types.ts` 与 [core-data-structures/bash.md](../../../docs/core-data-structures/bash.md)。

-`stdin` 与普通 `env` 由同进程插件（hooks 桥接、原生插件）设置，用于向 hook 命令提供其 JSON payload 和 `CLAUDE_PROJECT_DIR`／`CLAUDE_PLUGIN_ROOT` 值。`dshEnv` 是受类型限制、仅允许受管 key 的独立受信任 overlay；导出的 `DSH_ENV_PREFIX` 是该 namespace、其 `DshEnvironmentKey` 模板类型、执行器清理、注册表验证、派生内置名称与模型指引的统一来源。模型 bash 使用 `ctx.bashEnv` 收集的当前快照。实现会移除继承的受管 key，再在普通 `env` 之后合并 `dshEnv`，因此省略的当前事实不会回退到陈旧环境状态，`env` 条目也无法顶掉受管值。面向模型的工具不将这三者中的任何一个公开为参数。这三者在已解析 spec 上仍然可选；缺失表示没有输入／overlay。详见 [bash-stdin-env Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) 与 [会话环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。
+`stdin` 与普通 `env` 由同进程插件（hooks 桥接、原生插件）设置，用于向 hook 命令提供其 JSON payload 和 `CLAUDE_PROJECT_DIR`／`CLAUDE_PLUGIN_ROOT` 值。`dshEnv` 是受类型限制、仅允许受管 key 的独立受信任 overlay；导出的 `DSH_ENV_PREFIX` 是该 namespace、其 `DshEnvironmentKey` 模板类型、执行器清理、注册表验证、派生内置名称与模型指引的统一来源。模型 bash 使用 `ctx.bashEnv` 收集的当前快照。实现会移除继承的受管 key，再在普通 `env` 之后合并 `dshEnv`，因此省略的当前事实不会回退到陈旧环境状态，`env` 条目也无法顶掉受管值。面向模型的工具不将这三者中的任何一个公开为参数。这三者在已解析 spec 上仍然可选；缺失表示没有输入／overlay。详见 [bash-stdin-env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md) 与 [会话环境 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-agent-session-identity-and-log-location.md)。
+
+导出的 `parseExitStatus`（连同 `ParsedExitStatus`）是 shell 工具共享渲染契约的另一半：`dsh-tool-bash` 的 `renderResult` 与 `dsh-tool-pwsh` 的 `renderPwshResult` 追加的 `[exit code: N]`／`[killed by signal: X]` marker 的逆解析。两个工具的 `presentResult` 都用它把渲染文本拆成 terminal 卡的输出正文与其退出状态 pill；它放在 seam 上，两个工具便永远不会在 marker 契约上漂移。

 ## 模型体验

--- a/packages/bash/bash/package.json
+++ b/packages/bash/bash/package.json
@@ -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",
  "peerDependencies": {
--- a/packages/bash/bash/src/index.ts
+++ b/packages/bash/bash/src/index.ts
@@ -22,6 +22,8 @@ export type {
  DshEnvironment,
  DshEnvironmentKey,
 } from './types.ts'
+export { parseExitStatus } from './render.ts'
+export type { ParsedExitStatus } from './render.ts'

 declare module 'cordis' {
  interface Context {
--- a/packages/bash/bash/src/render.ts
+++ b/packages/bash/bash/src/render.ts
@@ -0,0 +1,42 @@
+/**
+ * Shared rendering helpers for the shell tools (`dsh-tool-bash`,
+ * `dsh-tool-pwsh`): the exit-status marker contract the tools' renderers
+ * emit and the presentation layer parses back.
+ * @module @deepseek-ai/dsh-bash/render
+ */
+
+/**
+ * The exit status recovered from a rendered result, with the output body that
+ * status was split off from.
+ */
+export type ParsedExitStatus =
+  & { body: string }
+  & ({ exitCode: number } | { signal: string })
+
+/**
+ * Split a rendered shell-tool result string into its output body and the
+ * structured exit status — the inverse of the `[exit code: N]` /
+ * `[killed by signal: X]` markers the shell tools' renderers append. A killed
+ * marker yields `signal`; otherwise a non-zero marker yields `exitCode`;
+ * absent both means a clean exit 0.
+ *
+ * The consumed marker is removed from `body` because a terminal presentation
+ * shows the exit status as its own pill: leaving the marker in the output
+ * would render the exit twice. Other markers (timeout, sandbox denial) carry
+ * facts no pill shows, so they stay in the body.
+ *
+ * Replay only retains the rendered content text, not the original
+ * `BashRunResult`, so terminal presentation must recover the exit pill here.
+ * Requiring a leading newline and the end of the string keeps ordinary output
+ * that merely ends with marker-like text from matching unless the final line
+ * is indistinguishable from a real marker.
+ * @param text - rendered model-facing shell-tool result.
+ * @returns the marker-free body plus the recovered terminal exit code or signal.
+ */
+export function parseExitStatus(text: string): ParsedExitStatus {
+  const signal = /\n\[killed by signal: ([^\]\n]+)\]$/.exec(text)
+  if (signal?.[1] !== undefined) return { body: text.slice(0, signal.index), signal: signal[1] }
+  const exit = /\n\[exit code: (\d+)\]$/.exec(text)
+  if (exit?.[1] !== undefined) return { body: text.slice(0, exit.index), exitCode: Number(exit[1]) }
+  return { body: text, exitCode: 0 }
+}
--- a/packages/bash/bash/tests/render.spec.ts
+++ b/packages/bash/bash/tests/render.spec.ts
@@ -0,0 +1,36 @@
+/**
+ * Shared exit-status parse contract: the inverse of the `[exit code: N]` /
+ * `[killed by signal: X]` markers `dsh-tool-bash` and `dsh-tool-pwsh` append.
+ * Both tools' presenter suites round-trip their own renderers through this
+ * parse; this spec pins the parse's own edges (marker-like output, body
+ * slicing) once, at the seam that owns it.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { parseExitStatus } from '../src/render.ts'
+
+describe('parseExitStatus', () => {
+  it('recovers a clean exit 0 with the body verbatim when no marker is present', () => {
+    expect(parseExitStatus('hi\n\n')).toEqual({ body: 'hi\n\n', exitCode: 0 })
+    expect(parseExitStatus('')).toEqual({ body: '', exitCode: 0 })
+  })
+
+  it('recovers a non-zero exit and strips only its marker from the body', () => {
+    expect(parseExitStatus('oops\n[exit code: 3]')).toEqual({ body: 'oops', exitCode: 3 })
+    // The marker needs the leading newline and the end of the string, so a
+    // clean result whose output merely ENDS in marker-like text is not read
+    // as a failure and the text stays in the body.
+    expect(parseExitStatus('[exit code: 5]')).toEqual({ body: '[exit code: 5]', exitCode: 0 })
+  })
+
+  it('recovers a signal kill ahead of any non-zero exit marker', () => {
+    expect(parseExitStatus('gone\n[killed by signal: SIGKILL]')).toEqual({ body: 'gone', signal: 'SIGKILL' })
+    // A fake signal marker with no leading newline is output, not a kill.
+    expect(parseExitStatus('[killed by signal: SIGKILL]')).toEqual({ body: '[killed by signal: SIGKILL]', exitCode: 0 })
+  })
+
+  it('keeps markers no pill shows (timeout) in the body', () => {
+    expect(parseExitStatus('slow\n[timed out after 100ms]\n[exit code: 143]'))
+      .toEqual({ body: 'slow\n[timed out after 100ms]', exitCode: 143 })
+  })
+})
--- a/packages/bash/pwsh-local/README.i18n.yaml
+++ b/packages/bash/pwsh-local/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/bash/pwsh-local/README.md
-README.md: 35ff7dba97b8109a99e649051166604fb279c408
-README.zh.md: fdba5baf00b50ce5384d9209c8fa01f42642491d
+README.md: 3e38ea3830cb651a80eaee744a42f68891767358
+README.zh.md: 8d32ce865d299bac37704e3e8730a7faa63ee108
--- a/packages/bash/pwsh-local/README.md
+++ b/packages/bash/pwsh-local/README.md
@@ -46,7 +46,7 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 ## Known Limitations and Deferred Work

 - **Unconfined by itself** — this executor always runs commands with the harness process's authority; deployments needing confinement compose a sandboxing bash executor or policy instead.
- **No persistent shell or PTY** — every call starts a fresh `pwsh -Command`; interactive terminal sessions remain deferred until the roadmap's pwsh TUI/GUI rendering work lands.
+- **No persistent shell or PTY** — every call starts a fresh `pwsh -Command`.
 - **The command string is PowerShell text** — the `-Command` domain has no shell-quoting layer, but a model-facing command is parsed by PowerShell itself, so PowerShell syntax errors are command failures, not launch failures.
 - **A background spawn-failure note is single-delivery** — the subprocess service buffers no output for a process that never ran, so the executor injects `spawn failed: …` into exactly one `readOutput()` delta; a reader that discards that delta cannot recover it.
 - **Windows termination reports no signal** — a force-killed process settles as exit 1 with `signal: null`, so signal-based status classification (POSIX `killed`) does not apply on Windows; `kill()`-initiated stops still stamp `killed` directly.
--- a/packages/bash/pwsh-local/README.zh.md
+++ b/packages/bash/pwsh-local/README.zh.md
@@ -46,7 +46,7 @@
 ## 已知局限与延期工作

 - **自身不设沙箱**——本执行器始终以 harness 进程的权限运行命令；需要约束的部署应组合沙箱化 bash 执行器或策略。
- **无持久 shell 或 PTY**——每次调用都是全新的 `pwsh -Command`；交互式终端会话在路线图的 pwsh TUI/GUI 渲染工作落地之前保持延期。
+- **无持久 shell 或 PTY**——每次调用都是全新的 `pwsh -Command`。
 - **命令字符串是 PowerShell 文本**——`-Command` 域没有 shell 引号层，但面向模型的命令由 PowerShell 自己解析，因此 PowerShell 语法错误是命令失败，而非启动失败。
 - **后台 spawn 失败提示只投递一次**——subprocess 服务不会为从未运行的进程缓冲输出，因此执行器只把 `spawn failed: …` 注入一次 `readOutput()` 增量；丢弃该增量的读取方无法恢复它。
 - **Windows 终止不报告信号**——被强制终止的进程以退出码 1、`signal: null` 结束，因此基于信号的状态分类（POSIX `killed`）在 Windows 上不适用；`kill()` 发起的停止仍会直接盖上 `killed`。
--- a/packages/bash/pwsh-local/package.json
+++ b/packages/bash/pwsh-local/package.json
@@ -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",
  "peerDependencies": {
--- a/packages/bash/tool-bash/README.i18n.yaml
+++ b/packages/bash/tool-bash/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/bash/tool-bash/README.md
-README.md: 35a5647365dab6daa903c14cba8b83702b50305d
-README.zh.md: eb7901f3445117988d77e6d39b73681480b7a754
+README.md: 47101e1198d13518c3d82877df8726c1fbf26b82
+README.zh.md: d60ac4b3826838e875f7d43bc314f62e1453c1d9
--- a/packages/bash/tool-bash/README.md
+++ b/packages/bash/tool-bash/README.md
@@ -6,7 +6,7 @@ The model-facing `bash` tool registered over the `ctx.bash` executor seam. Foreg

 Requires a loaded executor implementation (e.g. `@deepseek-ai/dsh-bash-local`) and the [`@deepseek-ai/dsh-bash-env`](../bash-env/README.md) registry; the plugin stays pending until every injected service exists (`inject: ['tools', 'bash', 'systemPrompt', 'bashEnv']`). The tool contract is bash-dialect — mount a bash-parsing executor.

-The package root exposes only the Cordis plugin contract (`name`, `inject`, `Config`, `apply`); result rendering and background-process adaptation remain implementation details covered by same-package tests.
+The package root exposes only the Cordis plugin contract (`name`, `inject`, `Config`, `apply`); result rendering and background-process adaptation remain package-internal.

 The plugin also contributes the `tool:bash` prompt section (order 105): check the `[exit code: N]` marker on every result and investigate failures before moving on.

--- a/packages/bash/tool-bash/README.zh.md
+++ b/packages/bash/tool-bash/README.zh.md
@@ -6,7 +6,7 @@

 需要加载执行器实现（例如 `@deepseek-ai/dsh-bash-local`）与 [`@deepseek-ai/dsh-bash-env`](../bash-env/README.md) 注册表；在每个注入服务就绪之前，插件会保持等待状态（`inject: ['tools', 'bash', 'systemPrompt', 'bashEnv']`）。工具契约是 bash 方言——请挂载能解析 bash 的执行器。

-包（package）根只公开 Cordis 插件契约（`name`、`inject`、`Config`、`apply`）；结果渲染和后台进程适配仍是实现细节，由同包测试覆盖。
+包（package）根只公开 Cordis 插件契约（`name`、`inject`、`Config`、`apply`）；结果渲染和后台进程适配仍保留在包内部。

 插件还会提供 `tool:bash` 提示词段落（顺序 105）：检查每个结果中的 `[exit code: N]` 标记，发现失败时先调查原因再继续。

@@ -42,7 +42,7 @@

 ## 工具仅使用具名参数构建请求

-`BashExecRequest` seam 携带可选的 `stdoutMaxBytes`、`stdin`、普通 `env` 和托管 `dshEnv`，供可信进程内插件及此工具的环境注册表使用。模型侧工具不公开 `stdoutMaxBytes`、`stdin` 或 `env`：它使用具名的命令／工作目录／超时／信号／沙箱字段，加上从注册表收集的 `dshEnv` 来构建请求。额外模型键会被忽略，无法替换托管值。Shell 语法可以提供等价的命令级行为，而本地执行器会清除环境中的凭据和陈旧 `DSH_*` 值。参见 [stdin/env Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md)。
+`BashExecRequest` seam 携带可选的 `stdoutMaxBytes`、`stdin`、普通 `env` 和托管 `dshEnv`，供可信进程内插件及此工具的环境注册表使用。模型侧工具不公开 `stdoutMaxBytes`、`stdin` 或 `env`：它使用具名的命令／工作目录／超时／信号／沙箱字段，加上从注册表收集的 `dshEnv` 来构建请求。额外模型键会被忽略，无法替换托管值。Shell 语法可以提供等价的命令级行为，而本地执行器会清除环境中的凭据和陈旧 `DSH_*` 值。参见 [stdin/env Agent Note](../../../.agents/notes/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md)。

 ## 权限与升权

--- a/packages/bash/tool-bash/package.json
+++ b/packages/bash/tool-bash/package.json
@@ -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",
  "peerDependencies": {
--- a/packages/bash/tool-bash/src/background.ts
+++ b/packages/bash/tool-bash/src/background.ts
@@ -16,10 +16,10 @@ import type { BashProcess } from '@deepseek-ai/dsh-bash'
 */
 export function processOutcome(proc: BashProcess): { status: 'completed' | 'killed'; detail: string } {
  // TODO(background-infrastructure-outcome): widen BashProcess with an explicit
-  // infrastructure-failure outcome, then map spawn failures and
-  // sandbox.runnerFailed to task `failed`. The current seam aliases a spawn
-  // failure with a signal-less kill and a runner failure with an ordinary
-  // wrapper exit; real nonzero command exits must remain `completed`.
+  // infrastructure-failure outcome, then map it to task `failed`. Restricted
+  // runner failures expose sandbox.runnerFailed, but unconfined spawn failures
+  // still alias a signal-less kill; real nonzero command exits must remain
+  // `completed`.
  if (proc.status === 'killed') {
    return { status: 'killed', detail: proc.signal !== null ? `signal: ${proc.signal}` : 'killed before exit' }
  }
--- a/packages/bash/tool-bash/src/render.ts
+++ b/packages/bash/tool-bash/src/render.ts
@@ -95,36 +95,9 @@ export function renderProcessRead(
 }

 /**
- * The exit status recovered from a rendered result, with the output body that
- * status was split off from.
+ * The exit-status parse is the shared marker-contract half of the shell-tool
+ * rendering story, owned by `@deepseek-ai/dsh-bash` so `dsh-tool-pwsh` reuses
+ * it (its renderer emits the same markers). Re-exported here to keep
+ * `../src/render.ts` a single import root for bash-tool consumers.
 */
-export type ParsedExitStatus =
-  & { body: string }
-  & ({ exitCode: number } | { signal: string })
-
-/**
- * Split a rendered {@link renderResult} string into its output body and the
- * structured exit status — the inverse of the status markers it appends. A
- * killed marker yields `signal`; otherwise a non-zero marker yields `exitCode`;
- * absent both means a clean exit 0.
- *
- * The consumed marker is removed from `body` because a terminal presentation
- * shows the exit status as its own pill: leaving the marker in the output would
- * render the exit twice. Other markers (timeout, sandbox denial) carry facts no
- * pill shows, so they stay in the body.
- *
- * Replay only retains the rendered content text, not the original
- * `BashRunResult`, so terminal presentation must recover the exit pill here.
- * Requiring a leading newline and the end of the string keeps ordinary output
- * that merely ends with marker-like text from matching unless the final line
- * is indistinguishable from a real marker.
- * @param text - rendered model-facing bash result.
- * @returns the marker-free body plus the recovered terminal exit code or signal.
- */
-export function parseExitStatus(text: string): ParsedExitStatus {
-  const signal = /\n\[killed by signal: ([^\]\n]+)\]$/.exec(text)
-  if (signal?.[1] !== undefined) return { body: text.slice(0, signal.index), signal: signal[1] }
-  const exit = /\n\[exit code: (\d+)\]$/.exec(text)
-  if (exit?.[1] !== undefined) return { body: text.slice(0, exit.index), exitCode: Number(exit[1]) }
-  return { body: text, exitCode: 0 }
-}
+export { parseExitStatus, type ParsedExitStatus } from '@deepseek-ai/dsh-bash'
--- a/packages/bash/tool-bash/tests/integration.spec.ts
+++ b/packages/bash/tool-bash/tests/integration.spec.ts
@@ -48,7 +48,7 @@ afterEach(() => {

 function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
  return new Promise((resolve) => {
-    const dispose = ctx.on('agent/status', (subject, status) => {
+    const dispose = ctx.on('agent/status', ({ agent: subject, status }) => {
      if (subject === agent && status === 'idle') {
        dispose()
        resolve()
@@ -174,7 +174,7 @@ describe('bash tool through the agent loop', () => {
    expect(resultText(toolResult)).toContain('[exit code: 9]')
  })

-  it('background: start ack → completion notice as user/message → task_output collects it', async () => {
+  it('background: start ack → pending completion notice → task_output collects it', async () => {
    // The task id is deterministic (a fresh LocalTaskService counts per kind from 1),
    // so the script can name `bash-1` without threading a generated id.
    const adapter = new MockAdapter([
@@ -194,20 +194,27 @@ describe('bash tool through the agent loop', () => {
    expect(resultText(firstResult)).toBe('started background task bash-1')

    // The task settles on its own; the tool-tasks notice listener injects a
-    // durable plugin-sourced user/message into the owning agent's session
-    // (settlement may race turn end, so poll for it).
+    // pending next-step message without waking the idle agent.
    const isNotice = (e: SessionEvent): e is SessionEvent<'user/message'> =>
      e.type === 'user/message' && e.data.source.kind === 'plugin'
-    await pollUntil(() => events(agent).some(isNotice))
-    const notice = events(agent).find(isNotice)!
-    expect(notice.data.content.some(
+    await pollUntil(() => agent.inbox.nextStep.some(message => message.source.kind === 'plugin'))
+    const pendingNotice = agent.inbox.nextStep.find(message => message.source.kind === 'plugin')!
+    expect(pendingNotice.content.some(
      block => block.type === 'text' && block.text.includes('background task bash-1 (bash: echo bg-ok) finished'),
    )).toBe(true)
-    expect(notice.data.source).toEqual({ kind: 'plugin', plugin: 'tool-tasks' })
+    expect(pendingNotice.source).toEqual({
+      kind: 'plugin',
+      plugin: 'tool-tasks',
+      form: 'notice',
+      summary: 'bash echo bg-ok [status: completed, exit code: 0]',
+    })

-    // The next turn collects the output through the generic task tool.
+    // The next turn first admits that notice as user/message, then collects
+    // the output through the generic task tool.
    agent.followup(createUserMessage({ content: [{ type: 'text', text: 'collect it' }], source: { kind: 'user' } }))
    await waitForIdle(ctx, agent)
+    const notice = events(agent).find(isNotice)!
+    expect(notice.data).toEqual(pendingNotice)
    const readResult = findEvent(events(agent), 'tool/result', 'last')
    expect(readResult.data.message.content[0].isError).toBe(false)
    expect(resultText(readResult)).toContain('bg-ok')
--- a/packages/bash/tool-pwsh/README.i18n.yaml
+++ b/packages/bash/tool-pwsh/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/bash/tool-pwsh/README.md
-README.md: dfe26a63684d61dcdd6f969c2c2261dac79325c7
-README.zh.md: 2344f8477e5b15f2c4d366dd82b46358eacbc1b7
+README.md: 78eb161f77b9524bc577b273abe59db6b931727c
+README.zh.md: 17696fe6d908838aaaca12e8179f2ad9cb780210
--- a/packages/bash/tool-pwsh/README.md
+++ b/packages/bash/tool-pwsh/README.md
@@ -36,7 +36,7 @@ When `run_in_background` is true, this plugin preflights `ctx.tasks.start()` bef

 ## UI presentation

-The tool owns its `presentCall`/`presentResult` render intent. A foreground call is a `terminal` card carrying command, description, and optional cwd; a `run_in_background` call is a `generic` card with the raw command, mirroring the bash tool's background presentation. A completed result is a `generic` card with the rendered output in a `console` fence. The bash tool's terminal card with its parsed exit-status pill has no pwsh counterpart yet — a PowerShell-aware presentation is roadmap work. These presenters are pure and replay-safe.
+The tool owns its `presentCall`/`presentResult` render intent. A foreground call is a `terminal` card carrying command, description, and optional cwd; a `run_in_background` call is a `generic` card with the raw command, mirroring the bash tool's background presentation. A completed foreground result is a `terminal` card too: the exit marker becomes the card's exit-status pill (`exitCode`/`signal`), and the marker-free body is the card's output — exactly the bash tool's terminal-card story, via the shared exit-status parse from `@deepseek-ai/dsh-bash`. Background acks and execution errors stay `generic` cards with the rendered output in a `console` fence. These presenters are pure and replay-safe.

 ## Model Experience

@@ -121,5 +121,4 @@ Append-only; newly visible content follows the reusable request prefix and does
 - **No sandbox escalation** — `sandbox_permissions`/`justification` are absent; escalation waits for a Windows-confining executor (the bash tool's sandbox surface is not mirrored).
 - **No persistent shell or PTY** — every call starts a fresh `pwsh -Command`; the PTY backends are Linux/macOS-only today, and a Windows ConPTY persistent shell is roadmap work.
 - **PowerShell-dialect contract** — the model must write PowerShell (native paths, `$env:` variables), not bash; there is no dialect translation.
- **Generic UI presentation** — results use the generic card; a PowerShell-aware terminal card with exit-status pill is roadmap work.
 - **Session-cwd identity is not canonicalized** — the workdir base is the session header cwd as-is, unlike the bash tool's sandbox-root-canonicalized identity; only the sandbox-less case applies here.
--- a/packages/bash/tool-pwsh/README.zh.md
+++ b/packages/bash/tool-pwsh/README.zh.md
@@ -19,8 +19,8 @@
 | `command` | string (required) | 通过 `pwsh -Command` 运行。调用之间不保留状态——用 `workdir`，不要用 `cd`。 |
 | `description` | string (required) | 命令的一行主动语态摘要（5-10 词），仅用于 UI/日志展示——不影响执行。 |
 | `timeoutMs` | number | 超时覆盖值（毫秒）。执行器应用其配置的默认值与上限。 |
-| `workdir` | string | 本次调用的工作目录。默认取调用 agent 的会话 cwd（`session.header.cwd`），使每个会话在自己的工作区运行；相对 `workdir` 基于同一身份解析。 |
-| `run_in_background` | boolean | 立即返回任务 id；不适用超时。 |
+| `workdir` | string | 本次调用的工作目录。默认取调用 agent（智能体）的会话 cwd（`session.header.cwd`），使每个会话在自己的工作区运行；相对 `workdir` 基于同一身份解析。 |
+| `run_in_background` | boolean | 立即返回 task id；不适用超时。 |

 `command`、`workdir` 与 `timeoutMs` 在执行前经 `ctx.bash.resolve()` 按执行器配置默认值解析。workdir 默认值在工具层于 `resolve()` 之前从调用 agent 的 `session.header.cwd` 取得——每次会话的 cwd 必须来自 `exec.agent`，因为 N 个会话共享一个执行器；仅当没有会话 cwd 时执行器才回退到自己的配置 / `process.cwd()`。

@@ -36,7 +36,7 @@

 ## UI presentation

-工具拥有自己的 `presentCall`/`presentResult` 呈现意图。前台调用是携带命令、描述与可选 cwd 的 `terminal` 卡；`run_in_background` 调用是携带原始命令的 `generic` 卡，镜像 bash 工具的后台呈现。完成的结果是以 `console` 围栏包裹渲染输出的 `generic` 卡。bash 工具那种带解析退出状态 pill 的 terminal 卡在 pwsh 侧暂无对应——PowerShell 感知的呈现属于路线图工作。这些 presenter 是纯函数且可重放。
+工具拥有自己的 `presentCall`/`presentResult` 呈现意图。前台调用是携带命令、描述与可选 cwd 的 `terminal` 卡；`run_in_background` 调用是携带原始命令的 `generic` 卡，镜像 bash 工具的后台呈现。完成的前台结果同样是 `terminal` 卡：退出 marker 变成卡片的退出状态 pill（`exitCode`/`signal`），去 marker 的正文成为卡片输出——与 bash 工具的 terminal 卡故事完全一致，经由 `@deepseek-ai/dsh-bash` 的共享退出状态解析。后台 ack 与执行错误保持 `generic` 卡，以 `console` 围栏包裹渲染输出。这些 presenter 是纯函数且可重放。

 ## Model Experience

@@ -121,5 +121,4 @@ ack 是固定短行；任务输出按读取有界。
 - **无 sandbox 升级** — 没有 `sandbox_permissions`/`justification`；升级等待 Windows-confining 执行器（bash 工具的 sandbox 面不被镜像）。
 - **无持久 shell 或 PTY** — 每次调用都启动全新的 `pwsh -Command`；PTY 后端目前仅限 Linux/macOS，Windows ConPTY 持久 shell 属于路线图工作。
 - **PowerShell 方言契约** — 模型必须写 PowerShell（原生路径、`$env:` 变量），而不是 bash；没有方言翻译。
- **通用 UI 呈现** — 结果使用 generic 卡；带退出状态 pill 的 PowerShell 感知 terminal 卡属于路线图工作。
 - **会话 cwd 身份不做规范化** — workdir 基座直接取会话头 cwd 原值，不同于 bash 工具经 sandbox-root 规范化的身份；此处只涉及无 sandbox 场景。
--- a/packages/bash/tool-pwsh/package.json
+++ b/packages/bash/tool-pwsh/package.json
@@ -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",
  "peerDependencies": {
--- a/packages/bash/tool-pwsh/src/index.ts
+++ b/packages/bash/tool-pwsh/src/index.ts
@@ -8,8 +8,9 @@
 * foreground and `run_in_background` execution (background handles register
 * with the generic `ctx.tasks` runtime), the managed `DSH_*` environment
 * through the shared `bash-env` registry, and the bash marker/truncation
- * rendering story. UI presentation stays on the existing generic/terminal
- * cards; a pwsh-specific rendering twin is roadmap work.
+ * rendering story. UI presentation mirrors the bash tool's too: a completed
+ * foreground call is a terminal card with the parsed exit-status pill, using
+ * the shared exit-status parse from `@deepseek-ai/dsh-bash`.
 *
 * @module @deepseek-ai/dsh-tool-pwsh
 */
@@ -25,6 +26,7 @@ import type {} from '@deepseek-ai/dsh-system-prompt'
 import type {} from '@deepseek-ai/dsh-tasks'
 import type {} from '@deepseek-ai/dsh-bash-env'
 import type { BashRunResult } from '@deepseek-ai/dsh-bash'
+import { parseExitStatus } from '@deepseek-ai/dsh-bash'
 import { processOutcome } from './background.ts'
 import { renderPwshProcessRead, renderPwshResult } from './render.ts'

@@ -297,10 +299,20 @@ export function apply(ctx: Context, config: Config = {}): void {
      }
    },
    /* jscpd:ignore-end */
-    presentResult: (_args: unknown, result: ToolResult): ToolResultView | undefined => {
+    /* jscpd:ignore-start -- the completed-result presentation mirrors presentBashResult's by design (Agent Note). */
+    presentResult: (args: unknown, result: ToolResult): ToolResultView | undefined => {
      const block = result.content.length === 1 ? result.content[0] : undefined
      if (block === undefined || block.type !== 'text') return undefined
-      return { card: 'generic', content: [{ type: 'text', text: `\`\`\`console\n${block.text.replace(/\n+$/, '')}\n\`\`\`` }] }
+      const raw = block.text
+      const isBackground = typeof args === 'object' && args !== null && (args as { run_in_background?: unknown }).run_in_background === true
+      // Background acknowledgements and errors have no terminal exit status.
+      if (isBackground || result.isError) {
+        return { card: 'generic', content: [{ type: 'text', text: `\`\`\`console\n${raw.replace(/\n+$/, '')}\n\`\`\`` }] }
+      }
+      // The exit marker becomes the card's exit pill, so it leaves the output body.
+      const { body, ...exit } = parseExitStatus(raw)
+      return { card: 'terminal', output: body, ...exit }
    },
+    /* jscpd:ignore-end */
  }))
 }
--- a/packages/bash/tool-pwsh/tests/tools.spec.ts
+++ b/packages/bash/tool-pwsh/tests/tools.spec.ts
@@ -28,7 +28,7 @@ import * as ToolPwsh from '@deepseek-ai/dsh-tool-pwsh'
 import * as BashEnvPlugin from '@deepseek-ai/dsh-bash-env'
 import type { BashProcessRead } from '@deepseek-ai/dsh-bash'
 import { processOutcome } from '../src/background.ts'
-import { renderPwshProcessRead } from '../src/render.ts'
+import { renderPwshProcessRead, renderPwshResult } from '../src/render.ts'

 const testToolSignal = new AbortController().signal

@@ -516,16 +516,16 @@ describe('background execution through the task runtime', () => {
 })

 describe('UI presentation', () => {
-  it('a real execute renders the console view through the tool definition presenter', async () => {
+  it('a real execute presents a completed foreground run as a terminal card with the parsed exit pill', async () => {
    const { ctx, bash } = await setup()
    bash.handler = () => runResult('hi\n')
    const args = { command: 'Write-Output hi', description: 'say hi' }
    const result = await call(ctx, 'pwsh', args)
    const view = ctx.tools.get('pwsh')?.presentResult?.(args, result)
-    expect(view).toEqual({
-      card: 'generic',
-      content: [{ type: 'text', text: '```console\nhi\n```' }],
-    })
+    // A terminal result keeps the RAW bytes (newlines intact) a terminal
+    // renderer needs; a clean run renders no exit marker, so the body is the
+    // raw output with a clean exit-0 pill, mirroring the bash tool.
+    expect(view).toEqual({ card: 'terminal', output: 'hi\n', exitCode: 0 })
  })

  it('the pending call view is a terminal card carrying command, description, and optional cwd', async () => {
@@ -553,6 +553,83 @@ describe('UI presentation', () => {
    })
  })

+  it('presentResult: a non-zero exit and a signal kill parse into exitCode / signal', async () => {
+    const { ctx } = await setup()
+    const present = ctx.tools.get('pwsh')
+    const args = { command: 'x', description: 'x' }
+    expect(present?.presentResult?.(args, { content: [{ type: 'text', text: 'oops\n[exit code: 3]' }], isError: false }))
+      .toEqual({ card: 'terminal', output: 'oops', exitCode: 3 })
+    expect(present?.presentResult?.(args, { content: [{ type: 'text', text: 'gone\n[killed by signal: SIGKILL]' }], isError: false }))
+      .toEqual({ card: 'terminal', output: 'gone', signal: 'SIGKILL' })
+  })
+
+  it('presentResult: markers a pill CANNOT show (timeout) stay in the terminal output', async () => {
+    const { ctx } = await setup()
+    const args = { command: 'x', description: 'x' }
+    expect(ctx.tools.get('pwsh')?.presentResult?.(
+      args,
+      { content: [{ type: 'text', text: 'slow\n[timed out after 100ms]\n[exit code: 143]' }], isError: false },
+    )).toEqual({ card: 'terminal', output: 'slow\n[timed out after 100ms]', exitCode: 143 })
+  })
+
+  it('presentResult exit parse is the inverse of renderPwshResult markers (round-trip)', async () => {
+    const { ctx } = await setup()
+    const present = ctx.tools.get('pwsh')!
+    const base = {
+      aborted: false,
+      timeoutMs: 1000,
+      stdout: { text: 'out', truncated: false },
+      stderr: { text: '', truncated: false },
+    }
+    const cases = [
+      { result: { ...base, exitCode: 0, signal: null, timedOut: false }, expect: { exitCode: 0 } },
+      { result: { ...base, exitCode: 7, signal: null, timedOut: false }, expect: { exitCode: 7 } },
+      { result: { ...base, exitCode: null, signal: 'SIGTERM' as const, timedOut: false }, expect: { signal: 'SIGTERM' } },
+      // A trapped-timeout run that exits 0 has no signal/exit marker → reads as exit 0 (it did exit 0).
+      { result: { ...base, exitCode: 0, signal: null, timedOut: true }, expect: { exitCode: 0 } },
+    ]
+    for (const c of cases) {
+      const rendered = renderPwshResult(c.result)
+      const out = present.presentResult!({ command: 'x', description: 'x' }, { content: [{ type: 'text', text: rendered }], isError: false })
+      // Drop card + output; the remaining fields are the parsed exit.
+      const { card: _c, output, ...exit } = out as { card: string; output?: string; exitCode?: number; signal?: string }
+      expect(exit).toEqual(c.expect)
+      // Whatever the parse consumed is gone from the body, so a card with an
+      // exit pill never shows the same status twice.
+      expect(output).not.toMatch(/\[exit code: \d+\]|\[killed by signal: /)
+    }
+  })
+
+  it('presentResult: a clean exit-0 whose output ENDS in marker-like text is NOT read as a failure', async () => {
+    const { ctx } = await setup()
+    const args = { command: 'Write-Output "[exit code: 5]"', description: 'print' }
+    // A successful command may print marker-like text. A clean result appends no marker or
+    // newline; parsing requires the leading newline emitted for real markers, so this stays exit 0.
+    const out = ctx.tools.get('pwsh')!.presentResult!(args, { content: [{ type: 'text', text: '[exit code: 5]' }], isError: false })
+    expect(out).toEqual({ card: 'terminal', output: '[exit code: 5]', exitCode: 0 })
+    // Same for a fake signal marker with no leading newline.
+    const sig = ctx.tools.get('pwsh')!.presentResult!(args, { content: [{ type: 'text', text: '[killed by signal: SIGKILL]' }], isError: false })
+    expect(sig).toEqual({ card: 'terminal', output: '[killed by signal: SIGKILL]', exitCode: 0 })
+  })
+
+  it('presentResult: a run_in_background ack is a generic card and carries no exit pill', async () => {
+    const { ctx } = await setup()
+    const result = ctx.tools.get('pwsh')!.presentResult!(
+      { command: 'Start-Sleep -Seconds 60', description: 'long wait', run_in_background: true },
+      { content: [{ type: 'text', text: 'started background task pwsh-1' }], isError: false },
+    )
+    expect(result).toEqual({ card: 'generic', content: [{ type: 'text', text: '```console\nstarted background task pwsh-1\n```' }] })
+  })
+
+  it('presentResult: an isError result is a generic card (no real process exit to report)', async () => {
+    const { ctx } = await setup()
+    const out = ctx.tools.get('pwsh')!.presentResult!(
+      { command: 'x', description: 'x' },
+      { content: [{ type: 'text', text: 'tool call aborted' }], isError: true },
+    )
+    expect(out).toEqual({ card: 'generic', content: [{ type: 'text', text: '```console\ntool call aborted\n```' }] })
+  })
+
  it('presentResult falls back to undefined for multi-block or non-text content', async () => {
    const { ctx } = await setup()
    const definition = ctx.tools.get('pwsh')
--- a/packages/bundle/README.i18n.yaml
+++ b/packages/bundle/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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/bundle/README.md
+README.md: 4759170435a80e85731446cef21d24fff2abed66
+README.zh.md: 1ef610a1b7b3c591c9a900e04f2d8096b0b086b9
--- a/packages/bundle/README.md
+++ b/packages/bundle/README.md
@@ -0,0 +1,13 @@
+# bundle/ — profile plugin bundles
+
+English | [中文](README.zh.md)
+
+Profile bundles: npm packages whose manifest declares `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`, making them installable patch layers for `dsh --profile` compositions ([profile contract](../ui/app-boot/README.md#profiles)). A bundle's substance is its patch list; some also ship runtime glue plugins their patch mounts.
+
+| Package | Role | ctx key |
+|---|---|---|
+| [`base/`](base/README.md) | The shared dsh core every profile applies first | — (patch only) |
+| [`web-app/`](web-app/README.md) | Browser surface: web patch layer + runtime glue plugin | mounts rows |
+| [`headless/`](headless/README.md) | One-shot task mode over base + web-app | mounts `headless-runner` |
+
+In-box bundles resolve from the dsh installation; out-of-tree bundles install into a profile through `dsh plugin --profile <name> add <package>`.
--- a/packages/bundle/README.zh.md
+++ b/packages/bundle/README.zh.md
@@ -0,0 +1,13 @@
+# bundle/ — profile 插件组合包
+
+[English](README.md) | 中文
+
+Profile 组合包：在 manifest（元数据清单）中声明 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包，因此可作为 patch 层安装进 `dsh --profile` 组合（[profile 契约](../ui/app-boot/README.md#profiles)）。组合包的实体是它的 patch 列表；有些组合包还附带由其 patch 挂载的运行时粘合插件。
+
+| 包 | 职责 | ctx key |
+|---|---|---|
+| [`base/`](base/README.md) | 每个 profile 最先应用的共享 dsh 核心 | —（仅 patch） |
+| [`web-app/`](web-app/README.md) | 浏览器表层：web patch 层 + 运行时粘合插件 | 挂载多条配置行 |
+| [`headless/`](headless/README.md) | 叠加在 base + web-app 之上的一次性任务模式 | 挂载 `headless-runner` |
+
+内置组合包从 dsh 安装目录解析；树外（out-of-tree）组合包通过 `dsh plugin --profile <name> add <package>` 安装进 profile。
--- a/packages/bundle/base/README.i18n.yaml
+++ b/packages/bundle/base/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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/bundle/base/README.md
+README.md: 301d397d4c87687b382665cf63af47ab5e3f85be
+README.zh.md: f007bc817b6cbad84725fe8abe72549cf67d8cd7
--- a/packages/bundle/base/README.md
+++ b/packages/bundle/base/README.md
@@ -0,0 +1,19 @@
+# `@deepseek-ai/dsh-base`
+
+English | [中文](README.zh.md)
+
+The shared dsh core as a profile bundle: [`cordis.patch.yml`](cordis.patch.yml) inserts every base plugin row — model adapters, tools, persistence, policy, settings/credentials, repository Plugins, telemetry — over the empty profile root, as the first layer of every profile's `dsh.profile.bundles` list. Later bundle layers (e.g. [`dsh-web-app`](../web-app/README.md)) and the user's profile `cordis.patch.yml` override these rows by id; a patch replaces a row's whole `config`, so mode-specific values live in mode bundles, not here. The package has no runtime API; the profile composer resolves the patch through the `dsh.bundle.patch` manifest field, never through code.
+
+The row set and its rationale are documented inline in the patch file; the [generated composition graph](../../../apps/cli/composition.md) renders it.
+
+## Model Experience
+
+Indirectly, through the inserted rows: this bundle selects the shipped persona-less prompt base, tool set, and DeepSeek adapter that mode bundles specialize, and contributes no model-visible text of its own.
+
+#### KV Cache effect
+
+None directly; each inserted row's package owns its effect.
+
+## Known Limitations and Deferred Work
+
+- **A patch replaces whole row configs** — profile overrides must restate every field a row keeps; there is no deep-merge layer.
--- a/packages/bundle/base/README.zh.md
+++ b/packages/bundle/base/README.zh.md
@@ -0,0 +1,19 @@
+# `@deepseek-ai/dsh-base`
+
+[English](README.md) | 中文
+
+以 profile 组合包形式交付的共享 dsh 核心：[`cordis.patch.yml`](cordis.patch.yml) 在空的 profile 根之上插入全部基础插件行——模型适配器、工具、持久化、策略、settings／credentials、repository 插件、遥测——作为每个 profile 的 `dsh.profile.bundles` 列表中的第一层。后续的组合包层（例如 [`dsh-web-app`](../web-app/README.md)）和用户 profile 的 `cordis.patch.yml` 按 id 覆盖这些行；patch 会替换目标行的整个 `config`，因此模式专属的值放在各模式组合包中，而不是这里。该包没有运行时 API；profile 组合器通过 manifest（元数据清单）的 `dsh.bundle.patch` 字段解析 patch，绝不通过代码。
+
+行集合及其设计依据以行内注释写在 patch 文件里；[生成的组合图](../../../apps/cli/composition.md)负责渲染它。
+
+## 模型体验
+
+通过插入的行间接产生影响：该组合包选定了随发行版交付的无 persona 提示词基座、工具集合与 DeepSeek 适配器，供各模式组合包进一步特化；它自身不贡献任何模型可见文本。
+
+#### KV Cache 影响
+
+无直接影响；每条插入行的影响归其所属的包负责。
+
+## 已知限制与延期工作
+
+- **patch 会替换整行 `config`**：profile 覆盖必须重述该行需要保留的每个字段；不存在深度合并层。
--- a/packages/bundle/base/cordis.patch.yml
+++ b/packages/bundle/base/cordis.patch.yml
@@ -0,0 +1,404 @@
+# The dsh-base bundle patch: the shared core of every dsh profile, applied as
+# ONE insert over the empty profile root. Later bundle patches and the user's
+# profile cordis.patch.yml address these rows by id, with the last write
+# winning per row.
+#
+# A patch replaces the targeted row's whole `config` rather than merging into
+# it, so a row whose value differs by mode does NOT live here: it belongs to
+# each mode bundle, keeping any single row down to one bundle layer plus the
+# user's. Mode-specific rows appear below only with shared plugin identity and
+# neutral defaults; each mode bundle restates its complete configuration.
+#
+# Row order carries no load semantics (activation is service-availability
+# driven); the grouping is for readers.
+
+- insert:
+    - id: timer
+      name: '@cordisjs/plugin-timer'
+
+    - id: hmr
+      name: '@cordisjs/plugin-hmr'
+      config:
+        root: ['.']
+
+    # The profile's cordis.patch.yml replaces this row's config to select exact GitHub
+    # repository Plugin generations. The app registers the DSH-owned runtime even
+    # when the list is empty so a later personal-config edit can load
+    # transactionally; one-shot headless runs consume the startup value only.
+    - id: repository-plugins
+      name: '@deepseek-ai/dsh-repository-plugin'
+
+    - id: llm
+      name: '@deepseek-ai/dsh-llm'
+
+    - id: session
+      name: '@deepseek-ai/dsh-session'
+
+    - id: session-title
+      name: '@deepseek-ai/dsh-session-title'
+      config:
+        fallbackMaxWords: 5
+        fallbackMaxBytes: 40
+        maxTitleBytes: 80
+
+    - id: session-title-llm
+      name: '@deepseek-ai/dsh-session-title-first-message-llm'
+      config:
+        targetWords: 5
+        targetCjkCharacters: 10
+        maxInputBytes: 4096
+        maxOutputTokens: 64
+        timeoutMs: 60000
+
+    - id: user-interaction
+      name: '@deepseek-ai/dsh-user-interaction'
+
+    - id: agent
+      name: '@deepseek-ai/dsh-agent'
+
+    - id: tasks
+      name: '@deepseek-ai/dsh-tasks-local'
+
+    - id: llm-retry
+      name: '@deepseek-ai/dsh-llm-retry'
+
+    # User-settings document (`$DSH_HOME/settings.yaml`, hot-reloaded): a
+    # `llm-deepseek:` or `llm-pi-ai:` section there overrides the adapter entries
+    # below without a restart, and is what the web Models page writes.
+    - id: settings
+      name: '@deepseek-ai/dsh-settings-local'
+
+    # Credential store: the live process environment over `$DSH_HOME/.env`
+    # (owner-only file, hot-reloaded). Adapters resolve their key references
+    # through it at each request, so no key is inlined in this file. The web
+    # Models page's key inputs write it through `credentials.set`; nothing hoists
+    # the document into the process environment, which would make every stored key
+    # read as an unrotatable ambient override.
+    - id: credentials
+      name: '@deepseek-ai/dsh-credentials-local'
+
+    # The pi-ai multi-provider twin, mounted dormant: zero routes (and no extra
+    # models in the picker) until a `llm-pi-ai:` settings section supplies provider
+    # profiles — then those routes register live, keys resolving per request
+    # through their apiKeyEnv references, and drop again when the section empties.
+    # Supplying those profiles is exactly what the web Models page does. Which
+    # adapters exist is composition; which providers run is the user's settings
+    # document.
+    - id: llm-pi-ai
+      name: '@deepseek-ai/dsh-llm-pi-ai'
+
+    - id: session-persistence-jsonl
+      name: '@deepseek-ai/dsh-session-persistence-jsonl'
+      config:
+        root: !!js dshHomePath('sessions')
+
+    # Raw configs can supply a process-local path or disable this shared session
+    # capability. The neutral default is process-local and opens only when used.
+    - id: session-query-sqlite
+      name: '@deepseek-ai/dsh-session-query-sqlite'
+      config:
+        path: ':memory:'
+        openAt: first-search
+
+    # Session telemetry, on for every dsh mode: mirrors every session-log
+    # event (assistant/chunk projected to first-of-step) plus ops markers onto
+    # OTLP/HTTP log records, streaming on the batch processor's cadence
+    # (10s/batch here) — not at exit; a crash loses at most the last unexported
+    # interval. No telemetry/record redaction rule is mounted yet, so exports
+    # are the raw captured copy; the deployment stance, env seams, and
+    # follow-ups are pinned in the web-telemetry-default-mount Agent Note.
+    # DSH_TELEMETRY_OTLP_URL overrides the production endpoint, and a non-empty
+    # DSH_TELEMETRY_DISABLED — any value, including '0'/'false' — opts the
+    # process out (the launchers patch the row disabled; config cannot disable
+    # a row). Exports carry the harness home's anonymous user id ($DSH_HOME/.userid,
+    # random UUID; delete the file to reset the identity) as the Resource's
+    # user.id. The exporter/processor values normally bound the shutdown drain
+    # to ~1s against an unreachable collector: exporter.timeoutMillis is both
+    # the per-attempt socket timeout and the retry deadline (1s effectively
+    # disables the SDK's 5-try backoff), while maxExportBatchSize == maxQueueSize
+    # (both explicit) makes the drain a single batch. The SDK awaits
+    # exporter.forceFlush() outside exportTimeoutMillis, so the backend's 3s
+    # shutdownTimeoutMillis is the load-bearing outer bound when a transport
+    # promise never settles. Every CLI exit path drains it by disposing the root
+    # on SIGINT/SIGTERM.
+    - id: telemetry-otel
+      name: '@deepseek-ai/dsh-session-telemetry-otel'
+      config:
+        shutdownTimeoutMillis: 3000
+        exporter:
+          url: !!js process.env.DSH_TELEMETRY_OTLP_URL ?? 'https://harness-telemetry.deepseeksvc.com/v1/logs'
+          compression: gzip
+          timeoutMillis: 1000
+        processor:
+          scheduledDelayMillis: 10000
+          maxQueueSize: 2048
+          maxExportBatchSize: 2048
+          exportTimeoutMillis: 1500
+
+    - id: subprocess
+      name: '@deepseek-ai/dsh-subprocess-local'
+
+    # Every shipped CLI mode starts with the same file-effect boundary.
+    # The environment remains an explicit deployment override; otherwise fresh
+    # sessions pin workspace-write + ask through the permission service below.
+    - id: sandbox
+      name: '@deepseek-ai/dsh-sandbox-local'
+
+    - id: sandbox-policy
+      name: '@deepseek-ai/dsh-sandbox-policy'
+      config:
+        mode: !!js process.env.DSH_PERMISSION_MODE ?? 'workspace-write'
+        workspaceRoot: !!js process.cwd()
+
+    - id: bash-sandbox
+      name: '@deepseek-ai/dsh-bash-sandbox'
+      config:
+        timeoutMs: 60000
+
+    - id: approval
+      name: '@deepseek-ai/dsh-user-approval'
+      config:
+        policy: !!js "(process.env.DSH_PERMISSION_MODE ?? 'workspace-write') === 'danger-full-access' ? 'never' : 'ask'"
+
+    - id: permission
+      name: '@deepseek-ai/dsh-permission'
+      config:
+        presets:
+          read-only:
+            sandbox: read-only
+            approval: ask
+          workspace-write:
+            sandbox: workspace-write
+            approval: ask
+          danger-full-access:
+            sandbox: danger-full-access
+            approval: never
+
+    - id: bash-env
+      name: '@deepseek-ai/dsh-bash-env'
+
+    - id: tool-bash
+      name: '@deepseek-ai/dsh-tool-bash'
+
+    - id: tool-tasks
+      name: '@deepseek-ai/dsh-tool-tasks'
+
+    - id: fs-policy
+      name: '@deepseek-ai/dsh-fs-policy'
+
+    - id: tool-fs
+      name: '@deepseek-ai/dsh-tool-fs'
+
+    - id: tool-fs-search
+      name: '@deepseek-ai/dsh-tool-fs-search'
+      config:
+        sampleOverCapGlobResults: false
+
+    - id: workspace-context
+      name: '@deepseek-ai/dsh-workspace-context'
+      config:
+        maxBytes: 65536
+
+    - id: skill
+      name: '@deepseek-ai/dsh-skill'
+
+    - id: skill-local
+      name: '@deepseek-ai/dsh-skill-local'
+
+    - id: tool-skill
+      name: '@deepseek-ai/dsh-tool-skill'
+
+    - id: commands
+      name: '@deepseek-ai/dsh-commands'
+
+    - id: goal
+      name: '@deepseek-ai/dsh-goal'
+
+    - id: goal-session
+      name: '@deepseek-ai/dsh-goal-session'
+
+    - id: command-goal
+      name: '@deepseek-ai/dsh-command-goal'
+
+    - id: plan-mode
+      name: '@deepseek-ai/dsh-plan-mode'
+      config:
+        section: |
+              You are in plan mode. Stay in plan mode until exit_plan_mode succeeds or the user switches the session mode. Imperative language to implement changes means plan the implementation, not execute it. A user's conversational agreement — including an answer confirming something you asked — approves nothing and does not end plan mode; fold the confirmed decision into the plan and submit it through exit_plan_mode.
+
+              Explore first. Use non-mutating reads, searches, static analysis, and checks to ground the plan in the actual repository. Do not edit or write files, change configuration, run formatters or code generation that rewrites tracked files, commit, or otherwise carry out the plan. Prefer existing functions and patterns over new machinery.
+
+              The tool catalog stays the same across modes for request-cache stability. These plan-mode rules override any later tool description or guidance that suggests using mutation tools; those tools remain listed only to keep the request shape stable. Do not use todo_write to track this planning phase: it tracks implementation after an approved plan, while the plan itself belongs in exit_plan_mode.
+
+              Resolve discoverable facts by inspection. Use ask_user_question only for user-owned choices or material ambiguity that inspection cannot answer. Do not ask the user where code lives or how current behavior works when you can find out.
+
+              Make the plan decision-complete: state the goal and success criteria; group implementation changes by subsystem; identify public API, schema, and data-flow changes; cover edge cases, failure modes, tests, acceptance criteria, and explicit assumptions. Keep it concise enough to review but detailed enough that another engineer can implement it without making design decisions.
+
+              When ready, call exit_plan_mode with the complete plan markdown, starting with a # title. Make exit_plan_mode the only and final tool call in that assistant response: it presents the plan for approval, and implementation begins only in a later step after approval. Do not paste the final plan as a plain reply or ask "should I proceed?" through prose or ask_user_question. If review rejects it, incorporate the feedback and present again. If the review channel is unavailable or aborted, stay in plan mode and ask the user to switch modes manually; do not proceed with implementation.
+
+    - id: token-meter
+      name: '@deepseek-ai/dsh-token-meter'
+
+    - id: compact-basic
+      name: '@deepseek-ai/dsh-compact-basic'
+
+    # Human `/compact`: one useful reduction below the automatic threshold. Backend
+    # independent, so it follows whichever compaction service this leaf mounts.
+    - id: command-compact
+      name: '@deepseek-ai/dsh-command-compact'
+
+    - id: subagent
+      name: '@deepseek-ai/dsh-subagent'
+
+    - id: subagent-spawn
+      name: '@deepseek-ai/dsh-subagent-spawn'
+      config:
+        providerName: spawn
+
+    - id: subagent-fork
+      name: '@deepseek-ai/dsh-subagent-fork'
+      config:
+        providerName: fork
+
+    # Continuable background children are selected per delegation tool. The
+    # separately loaded follow-up tool registers the one global `send_message`.
+    - id: tool-subagent-control
+      name: '@deepseek-ai/dsh-tool-subagent-control'
+
+    - id: tool-subagent-list-agents
+      name: '@deepseek-ai/dsh-tool-subagent-control/list-agents'
+
+    - id: tool-subagent
+      name: '@deepseek-ai/dsh-tool-subagent'
+      config:
+        provider: spawn
+        toolName: subagent
+        backgroundMode: continuable
+
+    - id: tool-subagent-fork
+      name: '@deepseek-ai/dsh-tool-subagent'
+      config:
+        provider: fork
+        toolName: subagent_fork
+        backgroundMode: continuable
+
+    # Optional direct-child return channel; absent from roots and one-shot agents.
+    - id: tool-subagent-report
+      name: '@deepseek-ai/dsh-tool-subagent-report'
+
+    - id: workflow-workerthread
+      name: '@deepseek-ai/dsh-workflow-workerthread'
+      config:
+        provider: spawn
+
+    - id: tool-workflow
+      name: '@deepseek-ai/dsh-tool-workflow'
+
+    - id: timeout-policy
+      name: '@deepseek-ai/dsh-timeout-policy'
+
+    - id: spill-local
+      name: '@deepseek-ai/dsh-spill-local'
+
+    - id: spill-policy
+      name: '@deepseek-ai/dsh-spill-policy'
+      config:
+        maxInlineBytes: 50000
+
+    # Durability checkpoints before each model request and top-level dispatch.
+    - id: session-checkpoint-policy
+      name: '@deepseek-ai/dsh-session-checkpoint-policy'
+
+    # Compacts oversized tool results before the broader conversation compactor
+    # runs, preserving the model-visible result within the configured budget.
+    - id: tool-result-prune
+      name: '@deepseek-ai/dsh-compact-tool-result-prune'
+      config:
+        thresholdChars: 8192
+        headChars: 4096
+        tailChars: 1024
+
+    - id: tool-todo
+      name: '@deepseek-ai/dsh-tool-todo'
+
+    # Persisted same-session goals reach the model and the slash menu here; the
+    # domain, driver, and `/goal` command are above.
+    - id: tool-goal
+      name: '@deepseek-ai/dsh-tool-goal'
+
+    # Fresh-agent Ralph iteration over a build-time-fixed script.
+    - id: tool-ralph
+      name: '@deepseek-ai/dsh-tool-ralph'
+      config:
+        subagentProvider: spawn
+        maxRounds: 64
+
+    - id: tool-str-replace-editor
+      name: '@deepseek-ai/dsh-tool-str-replace-editor'
+      config:
+        maxOutputChars: 16000
+
+    # Consecutive-repeat reminders on the tool chain.
+    - id: repeat-tool-guard
+      name: '@deepseek-ai/dsh-repeat-tool-guard'
+      config:
+        thresholds: [3, 5, 8]
+        argumentsPreviewChars: 500
+
+    # Every mode enables the stable web_search model surface. DeepSeek search
+    # resolves the same DEEPSEEK_API_KEY credential the Models page manages for
+    # chat, at each search; its Messages endpoint is separate from the
+    # chat-completions endpoint, so it takes its own base-URL override. Fetch stays
+    # disabled and no fetch provider is mounted: that provider defers SSRF
+    # protection and the model would choose the request target. Search is a full
+    # auxiliary model request with server-side retrieval, so this shipped DeepSeek
+    # route gets 60s while the provider-neutral tool default remains 30s.
+    - id: web
+      name: '@deepseek-ai/dsh-web'
+      config:
+        searchProvider: deepseek-official
+
+    - id: web-search-deepseek
+      name: '@deepseek-ai/dsh-web-search-deepseek'
+      config:
+        apiKeyEnv: DEEPSEEK_API_KEY
+        baseURL: !!js process.env.DEEPSEEK_SEARCH_BASE_URL
+
+    - id: tool-web
+      name: '@deepseek-ai/dsh-tool-web'
+      config:
+        fetch: false
+        searchTimeoutMs: 60000
+
+    # ── rows every mode mounts, whose values each overlay may state ──────────────
+
+    # The tool registry. Presentation mode is a deployment choice; omitting it here
+    # keeps the schema default (native).
+    - id: tools
+      name: '@deepseek-ai/dsh-tools'
+
+    # The deployment persona is a deployment choice; plan-mode and tool plugins own
+    # their own prompt sections.
+    - id: system-prompt
+      name: '@deepseek-ai/dsh-system-prompt'
+      config:
+        persona: ''
+
+    # Agents created at startup. The base stays empty; raw overlays may create
+    # agents, while Web creates sessions on client request.
+    - id: agent-loop
+      name: '@deepseek-ai/dsh-agent-loop'
+      config:
+        agents: []
+
+    # The sandboxed filesystem provider. `cwd` defaults to `process.cwd()`; an
+    # overlay can pin another workspace.
+    - id: fs-sandbox
+      name: '@deepseek-ai/dsh-fs-sandbox'
+
+    # The native DeepSeek adapter. No key or endpoint is inlined: both resolve per
+    # request from the `llm-deepseek:` settings section over this entry, with the
+    # key coming from the credential store below. Thinking defaults are a deployment
+    # choice.
+    - id: llm-deepseek
+      name: '@deepseek-ai/dsh-llm-deepseek'
--- a/packages/bundle/base/package.json
+++ b/packages/bundle/base/package.json
@@ -0,0 +1,111 @@
+{
+  "name": "@deepseek-ai/dsh-base",
+  "description": "The shared dsh core as a profile bundle: every profile's first patch layer, inserting the base plugin rows over the empty profile root",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "cordis.patch.yml",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dependencies": {
+    "@cordisjs/plugin-hmr": "workspace:*",
+    "@cordisjs/plugin-timer": "workspace:*",
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-agent-loop": "workspace:^",
+    "@deepseek-ai/dsh-bash-env": "workspace:^",
+    "@deepseek-ai/dsh-bash-sandbox": "workspace:^",
+    "@deepseek-ai/dsh-command-compact": "workspace:^",
+    "@deepseek-ai/dsh-command-goal": "workspace:^",
+    "@deepseek-ai/dsh-commands": "workspace:^",
+    "@deepseek-ai/dsh-compact-basic": "workspace:^",
+    "@deepseek-ai/dsh-compact-tool-result-prune": "workspace:^",
+    "@deepseek-ai/dsh-credentials-local": "workspace:^",
+    "@deepseek-ai/dsh-fs-policy": "workspace:^",
+    "@deepseek-ai/dsh-fs-sandbox": "workspace:^",
+    "@deepseek-ai/dsh-goal": "workspace:^",
+    "@deepseek-ai/dsh-goal-session": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-llm-deepseek": "workspace:^",
+    "@deepseek-ai/dsh-llm-pi-ai": "workspace:^",
+    "@deepseek-ai/dsh-llm-retry": "workspace:^",
+    "@deepseek-ai/dsh-permission": "workspace:^",
+    "@deepseek-ai/dsh-plan-mode": "workspace:^",
+    "@deepseek-ai/dsh-repeat-tool-guard": "workspace:^",
+    "@deepseek-ai/dsh-repository-plugin": "workspace:^",
+    "@deepseek-ai/dsh-sandbox-local": "workspace:^",
+    "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-session-checkpoint-policy": "workspace:^",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
+    "@deepseek-ai/dsh-session-query-sqlite": "workspace:^",
+    "@deepseek-ai/dsh-session-telemetry-otel": "workspace:^",
+    "@deepseek-ai/dsh-session-title": "workspace:^",
+    "@deepseek-ai/dsh-session-title-first-message-llm": "workspace:^",
+    "@deepseek-ai/dsh-settings-local": "workspace:^",
+    "@deepseek-ai/dsh-skill": "workspace:^",
+    "@deepseek-ai/dsh-skill-local": "workspace:^",
+    "@deepseek-ai/dsh-spill-local": "workspace:^",
+    "@deepseek-ai/dsh-spill-policy": "workspace:^",
+    "@deepseek-ai/dsh-subagent": "workspace:^",
+    "@deepseek-ai/dsh-subagent-fork": "workspace:^",
+    "@deepseek-ai/dsh-subagent-spawn": "workspace:^",
+    "@deepseek-ai/dsh-subprocess-local": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-tasks-local": "workspace:^",
+    "@deepseek-ai/dsh-timeout-policy": "workspace:^",
+    "@deepseek-ai/dsh-token-meter": "workspace:^",
+    "@deepseek-ai/dsh-tool-bash": "workspace:^",
+    "@deepseek-ai/dsh-tool-fs": "workspace:^",
+    "@deepseek-ai/dsh-tool-fs-search": "workspace:^",
+    "@deepseek-ai/dsh-tool-goal": "workspace:^",
+    "@deepseek-ai/dsh-tool-ralph": "workspace:^",
+    "@deepseek-ai/dsh-tool-skill": "workspace:^",
+    "@deepseek-ai/dsh-tool-str-replace-editor": "workspace:^",
+    "@deepseek-ai/dsh-tool-subagent": "workspace:^",
+    "@deepseek-ai/dsh-tool-subagent-control": "workspace:^",
+    "@deepseek-ai/dsh-tool-subagent-report": "workspace:^",
+    "@deepseek-ai/dsh-tool-tasks": "workspace:^",
+    "@deepseek-ai/dsh-tool-todo": "workspace:^",
+    "@deepseek-ai/dsh-tool-web": "workspace:^",
+    "@deepseek-ai/dsh-tool-workflow": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "@deepseek-ai/dsh-user-approval": "workspace:^",
+    "@deepseek-ai/dsh-user-interaction": "workspace:^",
+    "@deepseek-ai/dsh-web": "workspace:^",
+    "@deepseek-ai/dsh-web-search-deepseek": "workspace:^",
+    "@deepseek-ai/dsh-workflow-workerthread": "workspace:^",
+    "@deepseek-ai/dsh-workspace-context": "workspace:^"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}
--- a/packages/bundle/base/src/index.ts
+++ b/packages/bundle/base/src/index.ts
@@ -0,0 +1,9 @@
+/**
+ * @deepseek-ai/dsh-base — the shared dsh core as a profile bundle. The
+ * package's substance is `cordis.patch.yml`, declared by the `dsh.bundle.patch`
+ * manifest field and resolved by the profile composer through that field;
+ * this module carries no runtime API.
+ * @module @deepseek-ai/dsh-base
+ */
+
+export {}
--- a/packages/bundle/base/src/invariant.ts
+++ b/packages/bundle/base/src/invariant.ts
@@ -0,0 +1,28 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-base`.
+ * @module @deepseek-ai/dsh-base/invariant
+ */
+
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-base'
+
+/** Cordis companion plugin name. */
+export const name = 'base-bundle-invariant'
+/** Service required before the companion can register. */
+export const inject = ['invariants']
+
+// No runtime invariant: the package is a static patch-list carrier (a YAML
+// document of loader rows owned by other packages); it mounts no service,
+// emits no events, and owns no mutable relation to check. Each inserted row's
+// own package carries that row's invariants.
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
--- a/packages/bundle/base/tests/base.spec.ts
+++ b/packages/bundle/base/tests/base.spec.ts
@@ -0,0 +1,25 @@
+/**
+ * The bundle's substance is its patch file: the `dsh.bundle.patch` manifest
+ * field must name a real, parseable patch list.
+ */
+
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import * as yaml from 'js-yaml'
+import { entryListSchema } from '@cordisjs/plugin-include'
+
+describe('dsh-base bundle', () => {
+  it('declares a parseable patch list through the dsh.bundle.patch manifest field', () => {
+    const root = fileURLToPath(new URL('..', import.meta.url))
+    const manifest = JSON.parse(readFileSync(resolve(root, 'package.json'), 'utf8')) as { dsh?: { bundle?: { patch?: string } } }
+    expect(manifest.dsh?.bundle?.patch).toBe('./cordis.patch.yml')
+    const parsed = yaml.load(readFileSync(resolve(root, manifest.dsh!.bundle!.patch!), 'utf8'), { schema: entryListSchema })
+    expect(Array.isArray(parsed)).toBe(true)
+    // The base layer is one insert list over the empty profile root.
+    const rows = (parsed as { insert?: { id?: string }[] }[]).flatMap(patch => patch.insert ?? [])
+    expect(rows.length).toBeGreaterThan(50)
+    expect(rows.some(row => row.id === 'agent-loop')).toBe(true)
+  })
+})
--- a/packages/bundle/base/tsconfig.json
+++ b/packages/bundle/base/tsconfig.json
@@ -0,0 +1,18 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}
--- a/packages/bundle/headless/README.i18n.yaml
+++ b/packages/bundle/headless/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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/bundle/headless/README.md
+README.md: d08fb08e2aca3c4e5ccd733b37fc415d492974ca
+README.zh.md: 99a64ef04c4fd8fb0c6a979d3f09f1bd98b434a0
--- a/packages/bundle/headless/README.md
+++ b/packages/bundle/headless/README.md
@@ -0,0 +1,18 @@
+# `@deepseek-ai/dsh-headless`
+
+English | [中文](README.zh.md)
+
+The dsh one-shot bundle. [`cordis.patch.yml`](cordis.patch.yml) rides over [`dsh-base`](../base/README.md) + [`dsh-web-app`](../web-app/README.md): it moves the webserver to an OS-assigned port (parallel runs never collide), silences the URL line, and inserts this package's `headless-runner` plugin (config `{task}`). The runner drives one task turn through the in-process API carrier (`InProcessApiClient` over `toFetchHandler(ctx.apiProxy)`, so the full wire chain — serialization, zod, SSE framing — really runs), aggregates the turn's final assistant text, writes it to stdout, and requests exit (completed → 0, else 1) through the launcher-provided `ctx.headlessIo` seam. The Web composition stays mounted, so the running session is observable in a browser at the stderr-announced URL. The launcher patches the task text in (`dsh --profile headless "task"`), and fails loud when a task is given to a profile without this row.
+
+## Model Experience
+
+None, as the runner submits the task as an ordinary user message over the shared composition; prompts and tools belong to the base/web bundles.
+
+#### KV Cache effect
+
+None; the runner adds nothing to the request prefix.
+
+## Known Limitations and Deferred Work
+
+- **One turn only** — the runner anchors on the first message-triggered turn and exits at its end; queued follow-ups and multi-turn tasks are out of scope.
+- **`ctx.headlessIo` is launcher-owned** — booting the headless profile outside the `dsh` launcher fails loud at activation until the host provides the seam.
--- a/packages/bundle/headless/README.zh.md
+++ b/packages/bundle/headless/README.zh.md
@@ -0,0 +1,18 @@
+# `@deepseek-ai/dsh-headless`
+
+[English](README.md) | 中文
+
+dsh 一次性任务组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在 [`dsh-base`](../base/README.md) + [`dsh-web-app`](../web-app/README.md) 之上：把 webserver 移到 OS 分配的端口（并行运行绝不冲突），关闭 URL 行输出，并插入本包的 `headless-runner` 插件（配置为 `{task}`）。runner 通过进程内 API 载体（架在 `toFetchHandler(ctx.apiProxy)` 之上的 `InProcessApiClient`，因此序列化、zod、SSE（Server-Sent Events）帧封装这整条 wire 链路都会真实运行）驱动一个任务轮次，聚合该轮次最终的 assistant 文本，写到 stdout，再经启动器提供的 `ctx.headlessIo` seam 请求退出（完成 → 0，否则 1）。Web 组合保持挂载，因此运行中的会话可在浏览器中通过 stderr 公告的 URL 观察。启动器把任务文本 patch 进来（`dsh --profile headless "task"`）；如果向没有这一行的 profile 传入任务，则大声失败。
+
+## 模型体验
+
+无。runner 把任务作为普通用户消息经共享组合提交；提示词与工具归 base／web 组合包所有。
+
+#### KV Cache 影响
+
+无；runner 不向请求前缀添加任何内容。
+
+## 已知限制与延期工作
+
+- **只运行一个轮次**：runner 锚定第一个由消息触发的轮次，并在其结束时退出；排队的后续消息与多轮任务不在范围内。
+- **`ctx.headlessIo` 由启动器持有**：在 `dsh` 启动器之外启动 headless profile 会在激活时大声失败，直到宿主提供该 seam。
--- a/packages/bundle/headless/cordis.patch.yml
+++ b/packages/bundle/headless/cordis.patch.yml
@@ -0,0 +1,21 @@
+# The dsh-headless bundle patch: one-shot task mode over dsh-base +
+# dsh-web-app. The web composition stays mounted (the session is observable
+# in a browser while it runs); this layer silences the URL line and the
+# GUI-orientation surface context (this user is not in the GUI), moves the
+# webserver to an OS-assigned port so parallel headless runs never collide,
+# and mounts the one-shot runner. The launcher patches the runner's `task`.
+
+- id: webserver
+  config:
+    host: 127.0.0.1
+    port: 0
+
+- id: web-runtime
+  config:
+    mode: production
+    printUrl: false
+    surfaceContext: false
+
+- insert:
+    - id: headless-runner
+      name: '@deepseek-ai/dsh-headless'
--- a/packages/bundle/headless/package.json
+++ b/packages/bundle/headless/package.json
@@ -0,0 +1,54 @@
+{
+  "name": "@deepseek-ai/dsh-headless",
+  "description": "The dsh one-shot bundle: a patch layer over dsh-base + dsh-web-app plus the runner plugin driving one task turn through the in-process API carrier",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "cordis.patch.yml",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-host-apiproxy": "^0.0.1",
+    "@deepseek-ai/dsh-host-webserver": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@cordisjs/plugin-loader": "workspace:^",
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-host-apiproxy": "workspace:^",
+    "@deepseek-ai/dsh-host-webserver": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}
--- a/packages/bundle/headless/src/index.ts
+++ b/packages/bundle/headless/src/index.ts
@@ -0,0 +1,173 @@
+/**
+ * @deepseek-ai/dsh-headless — the one-shot headless bundle: the bundle patch
+ * (`cordis.patch.yml`) rides over dsh-base + dsh-web-app (the headless
+ * session is web-observable while it runs — same composition), and this
+ * runner plugin drives one task through the in-process API carrier
+ * (InProcessApiClient over toFetchHandler(ctx.apiProxy), so the full wire
+ * chain — serialization, zod, SSE framing — really runs), prints the final
+ * assistant text at agent quiescence, and exits (completed → 0, else 1). The
+ * task text arrives as launcher-patched config
+ * (`dsh --profile headless "task"`).
+ * @module @deepseek-ai/dsh-headless
+ */
+
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import { InProcessApiClient, toFetchHandler } from '@deepseek-ai/dsh-host-apiproxy'
+// Empty type imports carry the httpServer and agent/status Context merges used below.
+import type {} from '@deepseek-ai/dsh-host-webserver'
+import type {} from '@deepseek-ai/dsh-agent'
+// Empty type import carries the loader Context merge for the settlement await.
+import type {} from '@cordisjs/plugin-loader'
+import type { MuxFrame } from '@deepseek-ai/dsh-host-apiproxy/api'
+import type { RpcRequest, RpcResponse } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import type { SessionId } from '@deepseek-ai/dsh-session'
+
+/** Stable Cordis plugin name. */
+export const name = 'headless-runner'
+
+/** Services required before the one-shot turn can start. */
+export const inject = ['apiProxy', 'httpServer']
+
+/** Plugin config: the task, patched in by the launcher. */
+export interface Config {
+  /** The prompt text for the single turn. */
+  task: string
+}
+
+export const Config: z<Config> = z.object({
+  task: z.string().required(),
+})
+
+/** Outcome of one headless run: aggregated final text plus the last turn-end reason kind. */
+interface TurnOutcome {
+  text: string
+  reason: string
+}
+
+/**
+ * The process-facing effects of one run, injectable for tests: output
+ * streams and the exit request (the launcher wires it to its bounded
+ * shutdown controller).
+ */
+export interface HeadlessIo {
+  stdout: { write(chunk: string): unknown }
+  stderr: { write(chunk: string): unknown }
+  /** Request process exit with `code` after the tree disposes. */
+  exit(code: number): void
+}
+
+/** Host seam: the launcher provides the exit wiring before the tree mounts. */
+declare module 'cordis' {
+  interface Context {
+    /** Process-facing effects for the one-shot headless runner. */
+    headlessIo?: HeadlessIo
+  }
+}
+
+/** Unwrap an RpcResponse or fail loud: business errors print and exit 1. */
+async function unwrap<T>(response: RpcResponse<T>, io: HeadlessIo): Promise<T> {
+  if (response.result.ok) return response.result.value
+  const { code, message } = response.result.error
+  io.stderr.write(`dsh: ${code}: ${message}\n`)
+  io.exit(1)
+  // Exit is asynchronous (bounded tree disposal); park this turn forever so
+  // no further request rides a session that is already being torn down.
+  return new Promise<never>(() => {})
+}
+
+/**
+ * Consume mux frames until the agent reaches idle, per the one-shot CLI
+ * idle-to-idle contract: the stream opens immediately before the prompt, and
+ * its first observed turn/start begins the task. Text is the last committed
+ * assistant message of the whole interval (steering or injected work may run
+ * further turns before quiescence), and the outcome reason is the final
+ * turn/end's kind. Idleness is signalled out of band by the caller's
+ * `agent/status` subscription; the stream itself carries no status frame.
+ * @param frames - the mux stream opened before the prompt.
+ * @param sessionId - the headless session.
+ * @param idle - resolves when the agent reaches quiescence.
+ * @param io - process-facing effects for stream diagnostics.
+ * @returns the aggregated outcome.
+ */
+async function consumeUntilIdle(
+  frames: AsyncIterable<RpcRequest<MuxFrame>>,
+  sessionId: SessionId,
+  idle: Promise<void>,
+  io: HeadlessIo,
+): Promise<TurnOutcome> {
+  let started = false
+  let text = ''
+  let reason: string = 'error'
+  void (async () => {
+    try {
+      for await (const frame of frames) {
+        const payload = frame.payload
+        if (payload.type === 'stream/error') return
+        if (payload.type !== 'session/event' || payload.sessionId !== sessionId) continue
+        const event = payload.event
+        if (event.type === 'turn/start') {
+          started = true
+          continue
+        }
+        if (!started) continue
+        if (event.type === 'assistant/message') {
+          const joined = event.data.message.content.filter(block => block.type === 'text').map(block => block.text).join('')
+          if (joined !== '') text = joined
+        }
+        if (event.type === 'turn/end') reason = event.data.reason.kind
+      }
+    } catch (error: unknown) {
+      io.stderr.write(`dsh: event stream failed: ${String(error)}\n`)
+    }
+  })()
+  await idle
+  return { text, reason }
+}
+
+/**
+ * Run one headless task to quiescence and request exit (completed → 0, else 1).
+ * @param ctx - plugin context carrying apiProxy, httpServer, and the launcher's headlessIo.
+ * @param config - validated {@link Config}.
+ */
+export function apply(ctx: Context, config: Config): void {
+  const io = ctx.headlessIo
+  if (io === undefined) {
+    throw new Error('headless-runner: the launcher must provide ctx.headlessIo before the tree mounts')
+  }
+  // Fire-and-forget by design: the run outlives plugin activation, and every
+  // failure path inside ends in io.exit, not a rejection.
+  void (async () => {
+    // The Loader mounts sibling rows concurrently and this plugin's inject
+    // gate covers only apiProxy/httpServer; prompting before the agent loop,
+    // adapters, and tools settle would fail the turn on a half-mounted tree.
+    // The old launcher ran strictly after settled boot — preserve that.
+    // A tree disposed mid-settlement (early SIGTERM) has nothing to run.
+    await ctx.get('loader')?.await()
+    if (ctx.get('httpServer') === undefined) return
+    // The headless session is web-observable while it runs (same composition).
+    io.stderr.write(`dsh: observing at http://127.0.0.1:${String(ctx.httpServer.port)}\n`)
+    const api = new InProcessApiClient(toFetchHandler(ctx.apiProxy))
+    const created = await unwrap(await api.sessions.create({}), io)
+    // Open the stream before prompting so no frame is lost. The quiescence
+    // anchor below is an in-process ctx subscription, so a remote-carrier
+    // port of this runner must replace it with a wire-visible idle signal.
+    const abort = new AbortController()
+    const frames = api.events.mux({}, abort.signal)
+    const idle = new Promise<void>((resolve) => {
+      ctx.on('agent/status', ({ agent, status }) => {
+        if (agent.id === created.sessionId && status === 'idle') resolve()
+      })
+    })
+    const done = consumeUntilIdle(frames, created.sessionId, idle, io)
+    await unwrap(await api.sessions.prompt({
+      sessionId: created.sessionId,
+      mode: 'queue',
+      content: [{ type: 'text', text: config.task }],
+    }), io)
+    const outcome = await done
+    io.stdout.write(outcome.text + '\n')
+    abort.abort()
+    io.exit(outcome.reason === 'completed' ? 0 : 1)
+  })()
+}
--- a/packages/bundle/headless/src/invariant.ts
+++ b/packages/bundle/headless/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-headless`.
+ * @module @deepseek-ai/dsh-headless/invariant
+ */
+
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-headless'
+
+/** Cordis companion plugin name. */
+export const name = 'headless-invariant'
+/** Service required before the companion can register. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: the runner is a one-shot driver over the API carrier
+ * whose observable contract (final text on stdout, exit code by turn-end
+ * reason) is process-level and owned by the launcher e2e; it registers
+ * nothing and holds no mutable relation to audit inside the tree.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
--- a/packages/bundle/headless/tests/headless.spec.ts
+++ b/packages/bundle/headless/tests/headless.spec.ts
@@ -0,0 +1,218 @@
+/**
+ * One-shot runner behavior over a scripted in-process API: idle-to-idle
+ * aggregation (last text of the whole interval), exit-code mapping by the
+ * final turn-end reason, stream-error and RPC-error paths, and the
+ * launcher-owned `ctx.headlessIo` requirement.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { apply, Config, type HeadlessIo } from '../src/index.ts'
+
+interface ScriptedEvent { type: string; seq?: number; time?: number; sessionId?: string; data: Record<string, unknown> }
+
+let nextSeq = 0
+/** Stamp the envelope fields the wire schema requires. */
+function stamped(event: ScriptedEvent): ScriptedEvent {
+  nextSeq += 1
+  return { seq: nextSeq, time: nextSeq, ...event }
+}
+
+interface RpcShapedRequest { rpcId: string }
+
+/** Build a fake apiProxy (echoing rpcIds like the real gateway) whose mux stream replays `events` for the created session. */
+function scriptedApi(events: ScriptedEvent[], options: { promptFails?: boolean } = {}): unknown {
+  return {
+    sessions: {
+      create: (request: RpcShapedRequest) =>
+        Promise.resolve({ rpcId: request.rpcId, result: { ok: true, value: { sessionId: 'S1' } } }),
+      prompt: (request: RpcShapedRequest) => Promise.resolve(options.promptFails === true
+        // A code from the closed wire union: the carrier schema rejects invented codes.
+        ? { rpcId: request.rpcId, result: { ok: false, error: { code: 'agent-busy', message: 'agent is busy', details: { reason: 'test' } } } }
+        : { rpcId: request.rpcId, result: { ok: true, value: { accepted: true } } }),
+    },
+    events: {
+      mux: async function* () {
+        for (const event of events) {
+          if (event.type === 'stream/error') {
+            yield { rpcId: 'e', payload: { type: 'stream/error', error: { code: 'cancelled', message: 'stream broke', details: {} } } }
+            continue
+          }
+          const { sessionId = 'S1', ...rest } = event
+          yield { rpcId: 'e', payload: { type: 'session/event', sessionId, event: stamped(rest) } }
+        }
+      },
+    },
+  }
+}
+
+/**
+ * Mount the runner against a scripted API, emit the idle transition after the
+ * scripted frames drain, and wait for its exit request.
+ */
+async function run(events: ScriptedEvent[], options: { promptFails?: boolean } = {}): Promise<{ code: number; out: string; err: string }> {
+  const ctx = new Context()
+  let out = ''
+  let err = ''
+  const exited = new Promise<number>((resolve) => {
+    const io: HeadlessIo = {
+      stdout: { write: (chunk: string) => { out += chunk; return true } },
+      stderr: { write: (chunk: string) => { err += chunk; return true } },
+      exit: resolve,
+    }
+    ctx.provide('headlessIo', io)
+  })
+  ctx.provide('apiProxy', scriptedApi(events, options) as never)
+  ctx.provide('httpServer', { port: 12345 } as never)
+  apply(ctx, { task: 'do the thing' })
+  // Quiescence is out of band: give the scripted stream a beat to drain, then
+  // flip the agent idle exactly as the loop would. Foreign agents and
+  // non-idle transitions must not settle the run.
+  await new Promise(resolve => setTimeout(resolve, 10))
+  ctx.emit('agent/status', { agent: { id: 'OTHER' } as Agent, status: 'idle' })
+  ctx.emit('agent/status', { agent: { id: 'S1' } as Agent, status: 'running' })
+  ctx.emit('agent/status', { agent: { id: 'S1' } as Agent, status: 'idle' })
+  const code = await exited
+  await ctx.fiber.dispose()
+  return { code, out, err }
+}
+
+const startupTurn: ScriptedEvent = { type: 'turn/start', data: { turn: 0, trigger: { kind: 'startup' } } }
+const messageTurn: ScriptedEvent = { type: 'turn/start', data: { turn: 1, trigger: { kind: 'message' } } }
+const text = (turn: number, value: string): ScriptedEvent => ({
+  type: 'assistant/message',
+  data: { turn, message: { content: [{ type: 'text', text: value }] } },
+})
+const end = (turn: number, reason: string): ScriptedEvent => ({ type: 'turn/end', data: { turn, reason: { kind: reason } } })
+
+describe('headless runner', () => {
+  it('aggregates to quiescence: last text wins across turns, final turn-end reason maps to exit 0', async () => {
+    const { code, out, err } = await run([
+      // Frames before the first turn/start are outside the task interval.
+      { type: 'assistant/message', data: { turn: 0, message: { content: [{ type: 'text', text: 'pre-task noise' }] } } },
+      startupTurn,
+      // Off-session, non-text, and text-empty frames never affect the aggregate.
+      { type: 'assistant/message', sessionId: 'OTHER', data: { turn: 1, message: { content: [{ type: 'text', text: 'other session' }] } } },
+      { type: 'assistant/message', data: { turn: 1, message: { content: [{ type: 'tool_call', text: 'ignored' }] } } },
+      text(0, 'draft'),
+      end(0, 'completed'),
+      messageTurn,
+      text(1, 'final answer'),
+      end(1, 'completed'),
+    ])
+    expect(code).toBe(0)
+    expect(out).toBe('final answer\n')
+    expect(err).toContain('observing at http://127.0.0.1:12345')
+  })
+
+  it('exits 1 when the final turn ends for any other reason', async () => {
+    const { code } = await run([messageTurn, end(1, 'aborted')])
+    expect(code).toBe(1)
+  })
+
+  it('exits 1 when no turn ever starts (idle without work)', async () => {
+    const { code, out } = await run([])
+    expect(code).toBe(1)
+    expect(out).toBe('\n')
+  })
+
+  it('keeps the error outcome after a stream error ends the frame consumer early', async () => {
+    const { code } = await run([messageTurn, { type: 'stream/error', data: {} }, end(1, 'completed')])
+    // The consumer stopped at the stream error; the completed turn-end after
+    // it is never observed, so the reason stays 'error'.
+    expect(code).toBe(1)
+  })
+
+  it('prints an RPC business error and exits 1 without waiting for idle', async () => {
+    const ctx = new Context()
+    let err = ''
+    const exited = new Promise<number>((resolve) => {
+      ctx.provide('headlessIo', {
+        stdout: { write: () => true },
+        stderr: { write: (chunk: string) => { err += chunk; return true } },
+        exit: resolve,
+      } satisfies HeadlessIo)
+    })
+    ctx.provide('apiProxy', scriptedApi([messageTurn, end(1, 'completed')], { promptFails: true }) as never)
+    ctx.provide('httpServer', { port: 1 } as never)
+    apply(ctx, { task: 't' })
+    expect(await exited).toBe(1)
+    expect(err).toContain('agent-busy')
+    await ctx.fiber.dispose()
+  })
+
+  it('reports the stream-failed diagnostic when the event channel dies, still settling at idle', async () => {
+    const ctx = new Context()
+    let err = ''
+    const exited = new Promise<number>((resolve) => {
+      ctx.provide('headlessIo', {
+        stdout: { write: () => true },
+        stderr: { write: (chunk: string) => { err += chunk; return true } },
+        exit: resolve,
+      } satisfies HeadlessIo)
+    })
+    ctx.provide('apiProxy', {
+      sessions: {
+        create: (request: RpcShapedRequest) =>
+          Promise.resolve({ rpcId: request.rpcId, result: { ok: true, value: { sessionId: 'S1' } } }),
+        prompt: (request: RpcShapedRequest) =>
+          Promise.resolve({ rpcId: request.rpcId, result: { ok: true, value: { accepted: true } } }),
+      },
+      events: {
+        // Synchronous throw: the SSE response never forms, so the client-side
+        // iterable rejects — the runner's own catch path, not a carrier frame.
+        mux: () => { throw new Error('channel exploded') },
+      },
+    } as never)
+    ctx.provide('httpServer', { port: 1 } as never)
+    apply(ctx, { task: 't' })
+    await new Promise(resolve => setTimeout(resolve, 10))
+    ctx.emit('agent/status', { agent: { id: 'S1' } as Agent, status: 'idle' })
+    expect(await exited).toBe(1)
+    expect(err).toContain('event stream failed')
+    await ctx.fiber.dispose()
+  })
+
+  it('waits for Loader settlement and abandons the run when the tree died during it', async () => {
+    const ctx = new Context()
+    let err = ''
+    let exited = false
+    ctx.provide('headlessIo', {
+      stdout: { write: () => true },
+      stderr: { write: (chunk: string) => { err += chunk; return true } },
+      exit: () => { exited = true },
+    } satisfies HeadlessIo)
+    ctx.provide('apiProxy', scriptedApi([]) as never)
+    // The webserver is provided by a child fiber whose disposal (early
+    // SIGTERM during the boot window) removes the service; settlement
+    // resolves only afterwards, and the runner must abandon rather than
+    // crash on the torn-down port read.
+    const webserverFiber = ctx.plugin((childCtx: Context) => {
+      childCtx.provide('httpServer', { port: 1 } as never)
+    })
+    await webserverFiber
+    let release: () => void
+    const settlement = new Promise<void>((resolve) => { release = resolve })
+    ctx.provide('loader', { await: () => settlement } as never)
+    apply(ctx, { task: 't' })
+    await webserverFiber.dispose()
+    release!()
+    await new Promise(resolve => setTimeout(resolve, 10))
+    expect(err).toBe('')
+    expect(exited).toBe(false)
+    await ctx.fiber.dispose()
+  })
+
+  it('fails loud without the launcher-owned headlessIo seam', () => {
+    const ctx = new Context()
+    ctx.provide('apiProxy', scriptedApi([]) as never)
+    ctx.provide('httpServer', { port: 1 } as never)
+    expect(() => { apply(ctx, { task: 't' }) }).toThrow('must provide ctx.headlessIo')
+  })
+
+  it('validates config: the task is required', () => {
+    expect(() => new Config({ } as never)).toThrow()
+    expect(new Config({ task: 'x' })).toEqual({ task: 'x' })
+  })
+})
--- a/packages/bundle/headless/tsconfig.json
+++ b/packages/bundle/headless/tsconfig.json
@@ -0,0 +1,36 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/loader"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../host/apiproxy"
+    },
+    {
+      "path": "../../host/webserver"
+    },
+    {
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}
--- a/packages/bundle/web-app/README.i18n.yaml
+++ b/packages/bundle/web-app/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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/bundle/web-app/README.md
+README.md: 95cdbc9694b44539742e5b871157eefa7cb4c290
+README.zh.md: b8d6e9d80bac82a7798cc07d3a34c01d219f2174
--- a/packages/bundle/web-app/README.md
+++ b/packages/bundle/web-app/README.md
@@ -0,0 +1,26 @@
+# `@deepseek-ai/dsh-web-app`
+
+English | [中文](README.zh.md)
+
+The dsh browser-surface bundle. [`cordis.patch.yml`](cordis.patch.yml) rides over [`dsh-base`](../base/README.md): it sets the coding persona, inserts the Web host rows (webserver, API gateway, workspace, projection, storage) and the browser plugin roster, and mounts this package's own `web-runtime` glue plugin (config `{mode, printUrl, lanAddresses}`). That plugin owns what used to be launcher code: it resolves the built frontend dist through `@deepseek-ai/dsh-frontend`'s exports (workspace knowledge of this bundle, never user config), mounts the [`frontend-static`](../../host/frontend-static/README.md) fallback owner over it, registers the web-surface prompt section and the bash-visible `DSH_WEB_URL`/`DSH_WEB_MODE` runtime variables, and prints the `dsh web:` URL line when `printUrl` is true. The `dsh web` launcher alias patches `mode`/`lanAddresses`/`printUrl` and the flag family over these rows; [`dsh-headless`](../headless/README.md) layers on top and silences the URL line.
+
+## Model Experience
+
+### Web-surface prompt section and bash runtime variables
+
+#### What the model sees
+
+The `app:web-surface` global section (order −98) orients the model to the GUI: the canonical local URL, the "this page" referent, the HMR/rebuild update contract for the active mode, and the instruction not to start replacement servers. `DSH_WEB_URL` and `DSH_WEB_MODE` additionally appear in the managed bash environment with their descriptions, resolved per invocation from the live server.
+
+#### Token effect
+
+One prompt paragraph per session plus two managed-environment variable lines; constant per process.
+
+#### KV Cache effect
+
+The prompt section sits near the system prompt's head and is stable for the life of the process (port and mode are boot facts), so it does not invalidate the cache across turns.
+
+## Known Limitations and Deferred Work
+
+- **The frontend dist must be built** — `require.resolve` of the dist fails loud at activation with a build hint; there is no source-serving fallback.
+- **`lanAddresses` is a boot-time snapshot** — interface changes after boot are not re-advertised; the printed LAN URL always matches the configured trust fence.
--- a/packages/bundle/web-app/README.zh.md
+++ b/packages/bundle/web-app/README.zh.md
@@ -0,0 +1,26 @@
+# `@deepseek-ai/dsh-web-app`
+
+[English](README.md) | 中文
+
+dsh 浏览器表层组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在 [`dsh-base`](../base/README.md) 之上：设置 coding persona，插入 Web 宿主行（webserver、API 网关、workspace、投影、存储）与浏览器插件名录，并挂载本包自己的 `web-runtime` 粘合插件（配置为 `{mode, printUrl, lanAddresses}`）。该插件接管了原先属于启动器的代码：它通过 `@deepseek-ai/dsh-frontend` 的 exports 解析已构建的前端 dist（这是本组合包的 workspace 知识，绝不是用户配置），在其上挂载 [`frontend-static`](../../host/frontend-static/README.md) 回退席位所有者，注册 web 表层提示词段落和 bash 可见的 `DSH_WEB_URL`／`DSH_WEB_MODE` 运行时变量，并在 `printUrl` 为 true 时打印 `dsh web:` URL 行。`dsh web` 启动器别名把 `mode`／`lanAddresses`／`printUrl` 与相应 flag 家族 patch 到这些行上；[`dsh-headless`](../headless/README.md) 再叠加一层并关闭 URL 行。
+
+## 模型体验
+
+### Web 表层提示词段落与 bash 运行时变量
+
+#### 模型看到的内容
+
+全局段落 `app:web-surface`（顺序 −98）向模型说明 GUI：规范的本地 URL、「this page」指代什么、当前模式下 HMR（热模块替换）／重建的更新契约，以及不要启动替代服务器的指令。`DSH_WEB_URL` 与 `DSH_WEB_MODE` 还会连同各自描述出现在受管 bash 环境中，每次调用时从运行中的服务器解析。
+
+#### Token 影响
+
+每个会话一段提示词，外加两行受管环境变量；每个进程内保持恒定。
+
+#### KV Cache 影响
+
+该提示词段落位于系统提示词靠前位置，且在进程整个生命周期内稳定（端口与模式是启动期事实），因此不会使跨轮次缓存失效。
+
+## 已知限制与延期工作
+
+- **前端 dist 必须已构建**：对 dist 的 `require.resolve` 在激活时大声失败并给出构建提示；没有从源码直接服务的回退路径。
+- **`lanAddresses` 是启动期快照**：启动后的网卡变化不会重新公告；打印的 LAN URL 始终与配置的信任栅栏一致。
--- a/packages/bundle/web-app/cordis.patch.yml
+++ b/packages/bundle/web-app/cordis.patch.yml
@@ -0,0 +1,191 @@
+# The dsh-web-app bundle patch: the browser surface over the dsh-base layer.
+# Applied after dsh-base's insert; rows here override base rows by id, with
+# the profile's own cordis.patch.yml and any --patch overlays still to come.
+#
+# A patch replaces the targeted row's whole `config`, so each row below
+# restates every key it owns. The `dsh web` launcher alias turns --host/--port/
+# --dev/--workspace-root/--trusted-host into further patches over these rows
+# (`--dev` inserts the dsh-client-hmr row).
+
+# ── surface-specific values the base deliberately omits ─────────────────────
+
+- id: system-prompt
+  config:
+    persona: >-
+      You are a coding agent powered by the {{model}} model. Your working directory is {{cwd}}.
+
+# TODO: Re-enable shared HMR for Web after its reload lifecycle is tested.
+- id: hmr
+  disabled: true
+
+# Web content search runs on an ephemeral in-memory index. The service
+# activates at boot, while first-search defers the node:sqlite import and
+# in-memory handle so Node 22 startup stays quiet until content search
+# actually uses SQLite. That search then reconciles this boot's sources.
+- id: session-query-sqlite
+  config:
+    path: ':memory:'
+    openAt: first-search
+
+- id: tools
+  config:
+    # TEMPORARY workaround: DSH_TOOLS_MODE (native|code|both) opts a whole dsh
+    # process into Code Mode while per-session tool-mode selection is being
+    # designed; unset keeps the schema default (native). Remove the env seam
+    # once the web UI owns the choice per session.
+    mode: !!js process.env.DSH_TOOLS_MODE
+
+- id: llm-deepseek
+  config:
+    apiKey: !!js process.env.DEEPSEEK_API_KEY
+    baseURL: !!js process.env.DEEPSEEK_BASE_URL
+
+# ── web-only host rows, the transport layer, and the browser roster ─────────
+
+# `dshClient` rows are the browser roster the modules node half scans into
+# window.__DSH_BOOT__; the modules row is simultaneously a host row.
+- insert:
+    - id: session-projection
+      name: '@deepseek-ai/dsh-session-projection'
+
+    - id: code-runtime
+      name: '@deepseek-ai/dsh-code-runtime-worker'
+
+    - id: storage
+      name: '@deepseek-ai/dsh-storage'
+
+    - id: storage-json
+      name: '@deepseek-ai/dsh-storage-json'
+      config:
+        root: !!js dshHomePath('storages')
+
+    - id: storage-domain
+      name: '@deepseek-ai/dsh-storage-domain'
+      config:
+        backend: json
+
+    - id: workspace
+      name: '@deepseek-ai/dsh-workspace'
+
+    - id: session-projection-cache
+      name: '@deepseek-ai/dsh-session-projection-cache'
+      config:
+        writeEveryEvents: 200
+        writeIntervalMs: 5000
+
+    # Resolve bind host, SSH launch, and display once at boot, then mount the
+    # matching dual-face directory picker. Mount -native or -browse directly in
+    # an overlay to pin the interaction.
+    - id: directory-picker
+      name: '@deepseek-ai/dsh-host-directory-picker-auto'
+
+    # The API gateway: the transport-agnostic dispatch face every client shape
+    # shares. provider/model are the host default routing — the profile json's
+    # mapping target (user config overrides these engineering defaults).
+    - id: api-gateway
+      name: '@deepseek-ai/dsh-host-apiproxy'
+      config:
+        provider: deepseek-official
+        model: deepseek-v4-flash
+
+    # ── layer 2: transport/service ──────────────────────────────────────────────
+
+    # Plain route-registration carrier; host and port arrive as `dsh web`
+    # flag patches over these defaults. The dist is served by the web-runtime
+    # row below through the fallback seat.
+    - id: webserver
+      name: '@deepseek-ai/dsh-host-webserver'
+      config:
+        host: 127.0.0.1
+        port: 3080
+
+    # Web glue owned by this bundle: resolves the built frontend dist (an
+    # assembly fact of dsh-web-app, never user config), mounts the
+    # frontend-static fallback owner, registers the web-surface prompt
+    # section and bash runtime variables, and prints the URL line. `dsh web`
+    # patches mode/lanAddresses over these defaults.
+    - id: web-runtime
+      name: '@deepseek-ai/dsh-web-app'
+      config:
+        mode: production
+        printUrl: true
+
+    # ── browser plugin roster (dshClient rows; node halves are layer-2 hosts) ──
+
+    # Dual-face: node half scans this very tree for dshClient rows, composes
+    # window.__DSH_BOOT__, serves /plugins/<id>/client.js; browser half is the
+    # module table the shell kernel constructs before cordis exists (§4.7 —
+    # adopted as a plugin entry by the kernel, never fetched).
+    - id: modules
+      name: '@deepseek-ai/dsh-client-modules'
+
+    # Owns both ends of the web transport: node half binds the gateway to the
+    # webserver under /api; browser half is the fetch/SSE client.
+    - id: connection
+      name: '@deepseek-ai/dsh-client-connection'
+
+    - id: client-runtime
+      name: '@deepseek-ai/dsh-client-runtime'
+
+    - id: ui-theme
+      name: '@deepseek-ai/dsh-client-ui-theme'
+
+    - id: locale
+      name: '@deepseek-ai/dsh-client-locale'
+
+    - id: ui-layout
+      name: '@deepseek-ai/dsh-client-ui-layout'
+
+    - id: ui-sidebar
+      name: '@deepseek-ai/dsh-client-ui-sidebar'
+
+    - id: ui-settings
+      name: '@deepseek-ai/dsh-client-ui-settings'
+
+    - id: ui-settings-general
+      name: '@deepseek-ai/dsh-client-ui-settings-general'
+
+    - id: ui-models
+      name: '@deepseek-ai/dsh-client-ui-models'
+
+    - id: ui-conversation
+      name: '@deepseek-ai/dsh-client-ui-conversation'
+
+
+    - id: ui-workspace
+      name: '@deepseek-ai/dsh-client-ui-workspace'
+
+    # Input triggers: the '/' | '@' pipeline (ui-slash), the command surface over
+    # it (ui-command), and the two reference sources (ui-skill / ui-subagent).
+    - id: ui-slash
+      name: '@deepseek-ai/dsh-client-ui-slash'
+
+    - id: ui-command
+      name: '@deepseek-ai/dsh-client-ui-command'
+
+    - id: ui-skill
+      name: '@deepseek-ai/dsh-client-ui-skill'
+
+    - id: ui-subagent
+      name: '@deepseek-ai/dsh-client-ui-subagent'
+
+    # Goal surface: GoalBar in the input dock over the goal session projection.
+    - id: ui-goal
+      name: '@deepseek-ai/dsh-client-ui-goal'
+
+    # Model selection: the /model popupSelect + composer seat over session.models.
+    - id: ui-model
+      name: '@deepseek-ai/dsh-client-ui-model'
+
+    - id: ui-permission
+      name: '@deepseek-ai/dsh-client-ui-permission'
+
+    # Plan control: the composer plan seat over the plan projection + /plan channel.
+    - id: ui-plan
+      name: '@deepseek-ai/dsh-client-ui-plan'
+
+    - id: ui-question
+      name: '@deepseek-ai/dsh-client-ui-question'
+
+    - id: ui-trajectory
+      name: '@deepseek-ai/dsh-client-ui-trajectory'
--- a/packages/bundle/web-app/package.json
+++ b/packages/bundle/web-app/package.json
@@ -0,0 +1,86 @@
+{
+  "name": "@deepseek-ai/dsh-web-app",
+  "description": "The dsh browser-surface bundle: the web patch layer over dsh-base plus the runtime glue plugin (frontend dist serving, web-surface prompt, bash runtime variables, URL line)",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "cordis.patch.yml",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dependencies": {
+    "@deepseek-ai/dsh-client-connection": "workspace:^",
+    "@deepseek-ai/dsh-client-hmr": "workspace:^",
+    "@deepseek-ai/dsh-client-locale": "workspace:^",
+    "@deepseek-ai/dsh-client-modules": "workspace:^",
+    "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-command": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-conversation": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-goal": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-layout": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-model": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-models": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-permission": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-plan": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-question": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-settings": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-settings-general": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-sidebar": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-skill": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slash": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-subagent": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-theme": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-trajectory": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-workspace": "workspace:^",
+    "@deepseek-ai/dsh-code-runtime-worker": "workspace:^",
+    "@deepseek-ai/dsh-frontend": "workspace:^",
+    "@deepseek-ai/dsh-frontend-static": "workspace:^",
+    "@deepseek-ai/dsh-host-apiproxy": "workspace:^",
+    "@deepseek-ai/dsh-host-directory-picker-auto": "workspace:^",
+    "@deepseek-ai/dsh-host-directory-picker-browse": "workspace:^",
+    "@deepseek-ai/dsh-host-directory-picker-native": "workspace:^",
+    "@deepseek-ai/dsh-host-webserver": "workspace:^",
+    "@deepseek-ai/dsh-session-projection": "workspace:^",
+    "@deepseek-ai/dsh-session-projection-cache": "workspace:^",
+    "@deepseek-ai/dsh-storage": "workspace:^",
+    "@deepseek-ai/dsh-storage-domain": "workspace:^",
+    "@deepseek-ai/dsh-storage-json": "workspace:^",
+    "@deepseek-ai/dsh-workspace": "workspace:^",
+    "schemastery": "^3.18.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-bash-env": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-bash-env": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}
--- a/packages/bundle/web-app/src/index.ts
+++ b/packages/bundle/web-app/src/index.ts
@@ -0,0 +1,157 @@
+/**
+ * @deepseek-ai/dsh-web-app — the browser-surface bundle's runtime glue plugin
+ * plus the bundle patch (`cordis.patch.yml`, declared by the `dsh.bundle.patch`
+ * manifest field). The plugin owns what used to be launcher code: it resolves
+ * the built frontend dist (workspace knowledge of this bundle, never user
+ * config), mounts the `frontend-static` fallback owner over it, registers the
+ * web-surface prompt section and the bash-visible web runtime variables, and
+ * prints the URL line when configured to. Flag-derived values (`mode`,
+ * `lanAddresses`, `printUrl`) arrive as launcher patches over this row.
+ * @module @deepseek-ai/dsh-web-app
+ */
+
+import { createRequire } from 'node:module'
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import * as FrontendStatic from '@deepseek-ai/dsh-frontend-static'
+import type {} from '@cordisjs/plugin-loader'
+import type {} from '@deepseek-ai/dsh-host-webserver'
+import type {} from '@deepseek-ai/dsh-system-prompt'
+import type {} from '@deepseek-ai/dsh-bash-env'
+
+/** Stable Cordis plugin name. */
+export const name = 'web-app'
+
+/** Services required before the web runtime can mount. */
+export const inject = ['httpServer']
+
+/** Web runtime mode: production, or development when the client-plugin HMR receiver is active. */
+export type WebMode = 'production' | 'development'
+
+/** Plugin config: the surface facts the launcher patches over this bundle's defaults. */
+export interface Config {
+  /** Whether this process mounted the client-plugin HMR receiver (`dsh web --dev`). */
+  mode: WebMode
+  /** Print the URL line on activation; a headless layer over this bundle turns it off. */
+  printUrl: boolean
+  /**
+   * Register the model-visible surface context (the `app:web-surface` prompt
+   * section and the `DSH_WEB_URL`/`DSH_WEB_MODE` bash variables). A one-shot
+   * layer turns it off: its user is not interacting through the GUI, so the
+   * orientation text would be false.
+   */
+  surfaceContext: boolean
+  /**
+   * LAN IPv4 addresses sampled once by the launcher when the effective bind
+   * is all-interfaces — the exact snapshot the /api trust fence was
+   * configured with, so the printed LAN URL can never name an address the
+   * fence rejects. Empty on a loopback bind.
+   */
+  lanAddresses: string[]
+}
+
+export const Config: z<Config> = z.object({
+  mode: z.union([z.const('production'), z.const('development')]).default('production'),
+  printUrl: z.boolean().default(true),
+  surfaceContext: z.boolean().default(true),
+  lanAddresses: z.array(String).default([]),
+})
+
+/** Environment variable naming the canonical local URL of this Web GUI. */
+const DSH_WEB_URL = 'DSH_WEB_URL' as const
+/** Environment variable naming the Web runtime mode. */
+const DSH_WEB_MODE = 'DSH_WEB_MODE' as const
+
+// Display-only mirror of the webserver schema's loopback host: the address the
+// local URL always prints. Not a source of truth — the schema is.
+const LOOPBACK_HOST = '127.0.0.1'
+
+/** Model-visible orientation and acceptance boundary for sessions created through `dsh web`. */
+function webSurfacePrompt(webUrl: string, mode: WebMode): string {
+  const updateContract = mode === 'development'
+    ? 'This Web process was launched with `dsh web --dev`, so its client-plugin HMR receiver is active. '
+      + 'No-refresh updates occur only when `pnpm run dev:web` is also running from this same checkout to rebuild client-plugin bundles; verify that watcher before promising automatic updates. '
+      + 'Client-plugin changes then reload automatically, while apps/web shell and other plain-package changes still require a rebuild and page refresh. '
+    : 'This Web process was launched without `--dev`, so HMR is inactive: rebuild the affected Web artifacts and verify this existing URL after a page refresh. '
+      + 'If the user wants no-refresh client-plugin updates, explain that this GUI must be restarted with `dsh web --dev` and `pnpm run dev:web` must also run from this same checkout; do not present either command alone as sufficient. '
+  return `You are interacting with the user through the DeepSeek Harness Web GUI at ${webUrl}. `
+    + 'When the user refers to "this page", "this GUI", or "this app" without naming another target, they mean this GUI. '
+    + 'The browser provides no implicit DOM, route, or screenshot context. '
+    + updateContract
+    + 'Starting another server does not update this GUI. '
+    + 'The apps/web Vite entry builds the shell but is not a standalone application because only dsh web injects window.__DSH_BOOT__. '
+    + 'Do not start a replacement server unless the user asks; if one is needed, use a managed background task and verify its exact URL.'
+}
+
+/** Resolve the canonical loopback URL from the active Web server. */
+function localWebUrl(ctx: Context): string {
+  const port = ctx.get('httpServer')?.port
+  if (port === undefined) throw new Error('web-app: httpServer service missing while resolving Web runtime')
+  return `http://${LOOPBACK_HOST}:${String(port)}`
+}
+
+/** Dist location is workspace knowledge of this bundle: resolved through the frontend package exports, not configured. */
+function resolveDistIndex(): string {
+  const require = createRequire(import.meta.url)
+  try {
+    return require.resolve('@deepseek-ai/dsh-frontend/dist/index.html')
+  } catch {
+    /* v8 ignore next 2 -- reachable only on a checkout without a built dist; the test tree builds it */
+    throw new Error('web-app: frontend dist not built; run pnpm run build from the repository root first')
+  }
+}
+
+/** Test seam: hosts with no built frontend dist substitute the resolver; production never touches this. */
+export const internals: { resolveDistIndex: () => string } = { resolveDistIndex }
+
+/**
+ * Mount the Web runtime: dist serving, surface prompt, bash runtime
+ * variables, and the URL line.
+ * @param ctx - plugin context carrying the httpServer service.
+ * @param config - validated {@link Config}.
+ */
+export function apply(ctx: Context, config: Config): void {
+  ctx.plugin(FrontendStatic, { distIndex: internals.resolveDistIndex() })
+  if (config.surfaceContext) {
+    ctx.inject(['systemPrompt'], (promptCtx) => {
+      promptCtx.systemPrompt.section({
+        name: 'app:web-surface',
+        order: -98,
+        text: () => webSurfacePrompt(localWebUrl(promptCtx), config.mode),
+      })
+    })
+    ctx.inject(['bashEnv'], (runtimeCtx) => {
+      runtimeCtx.bashEnv.register({
+        name: 'web-runtime',
+        variables: {
+          [DSH_WEB_URL]: { description: 'Canonical local URL of the DeepSeek Harness Web GUI serving this session.' },
+          [DSH_WEB_MODE]: { description: 'Web runtime mode: production, or development when the client-plugin HMR receiver is active.' },
+        },
+        resolve: () => ({ [DSH_WEB_URL]: localWebUrl(runtimeCtx), [DSH_WEB_MODE]: config.mode }),
+      })
+    })
+  }
+  if (config.printUrl) {
+    // The URL line is a readiness signal: supervisors (and the keyless CLI
+    // smoke) RPC as soon as they observe it, so it must not print while
+    // sibling rows (the /api route owner) are still mounting. Await Loader
+    // settlement first; a hand-built tree without a Loader prints at once.
+    const printUrl = (): void => {
+      // The launcher's boot-time LAN snapshot, not a fresh sample: the printed
+      // LAN URL must name an address the /api trust fence was configured with.
+      const lanCandidate = config.lanAddresses[0]
+      const port = ctx.httpServer.port
+      console.log(`dsh web: ${localWebUrl(ctx)}${lanCandidate === undefined ? '' : ` (LAN: http://${lanCandidate}:${String(port)})`}`)
+    }
+    const loader = ctx.get('loader')
+    if (loader === undefined) printUrl()
+    else {
+      void loader.await().then(() => {
+        // The tree can be disposed while settlement was in flight (early
+        // SIGTERM); a URL line for a dead server would only mislead, and
+        // reading the torn-down port would turn a clean shutdown into a crash.
+        if (ctx.get('httpServer') !== undefined) printUrl()
+      })
+    }
+  }
+}
--- a/packages/bundle/web-app/src/invariant.ts
+++ b/packages/bundle/web-app/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-web-app`.
+ * @module @deepseek-ai/dsh-web-app/invariant
+ */
+
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-web-app'
+
+/** Cordis companion plugin name. */
+export const name = 'web-app-invariant'
+/** Service required before the companion can register. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: every contribution (frontend-static child plugin,
+ * prompt section, bashEnv registration) is registry-disposed with the fiber,
+ * and each owning registry's package carries that relation's invariant; the
+ * package holds no mutable state of its own to audit.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
--- a/packages/bundle/web-app/tests/web-app.spec.ts
+++ b/packages/bundle/web-app/tests/web-app.spec.ts
@@ -0,0 +1,197 @@
+/**
+ * Web runtime glue behavior: dist resolution through the bundle's own seam,
+ * the frontend-static child claiming the fallback seat, the web-surface
+ * prompt section and bash runtime variables, and URL-line printing with the
+ * launcher's LAN snapshot.
+ */
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import type { HttpServerService } from '@deepseek-ai/dsh-host-webserver'
+import { apply, Config, internals } from '../src/index.ts'
+
+let dist: string | undefined
+
+afterEach(() => {
+  vi.restoreAllMocks()
+  internals.resolveDistIndex = originalResolve
+  if (dist !== undefined) rmSync(dist, { recursive: true, force: true })
+  dist = undefined
+})
+
+const originalResolve = internals.resolveDistIndex
+
+/** Stage a dist fixture and point the bundle's resolver at it. */
+function stageDist(): string {
+  dist = mkdtempSync(join(tmpdir(), 'dsh-web-app-'))
+  mkdirSync(join(dist, 'dist'))
+  const index = join(dist, 'dist', 'index.html')
+  writeFileSync(index, '<head></head><body>shell</body>')
+  internals.resolveDistIndex = () => index
+  return index
+}
+
+/** A fake httpServer capturing the fallback seat and index taps. */
+function fakeHttpServer(): { server: HttpServerService; seat: () => unknown } {
+  let fallback: unknown
+  const server = {
+    port: 4567,
+    registerFallback: (handler: unknown) => {
+      fallback = handler
+      return () => { fallback = undefined }
+    },
+    applyIndexTaps: (html: string) => html,
+  } as unknown as HttpServerService
+  return { server, seat: () => fallback }
+}
+
+interface BashContribution {
+  name: string
+  variables: Record<string, { description: string }>
+  resolve: () => Record<string, string>
+}
+
+describe('web-app runtime glue', () => {
+  it('mounts dist serving, prompt section, bash variables, and prints the URL with the LAN snapshot', async () => {
+    stageDist()
+    const ctx = new Context()
+    const { server, seat } = fakeHttpServer()
+    ctx.provide('httpServer', server)
+    const contributions: BashContribution[] = []
+    ctx.provide('bashEnv', {
+      register: (contribution: BashContribution) => {
+        contributions.push(contribution)
+        return () => {}
+      },
+    } as never)
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
+    apply(ctx, new Config({ mode: 'development', printUrl: true, surfaceContext: true, lanAddresses: ['192.168.1.5'] }))
+    await ctx.plugin(SystemPrompt, { persona: '' })
+    // Settle the injected registrations.
+    await new Promise(resolve => setTimeout(resolve, 0))
+
+    expect(seat()).toBeDefined() // frontend-static claimed the fallback
+    expect(log).toHaveBeenCalledWith('dsh web: http://127.0.0.1:4567 (LAN: http://192.168.1.5:4567)')
+    const assembly = await ctx.systemPrompt.assemble()
+    const section = assembly.sections.find(entry => entry.name === 'app:web-surface')
+    expect(section?.text).toContain('http://127.0.0.1:4567')
+    expect(section?.text).toContain('--dev')
+    const webRuntime = contributions.find(contribution => contribution.name === 'web-runtime')
+    expect(webRuntime?.resolve()).toEqual({ DSH_WEB_URL: 'http://127.0.0.1:4567', DSH_WEB_MODE: 'development' })
+    await ctx.fiber.dispose()
+  })
+
+  it('stays quiet in production mode with printUrl off and reports the production update contract', async () => {
+    stageDist()
+    const ctx = new Context()
+    ctx.provide('httpServer', fakeHttpServer().server)
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
+    apply(ctx, new Config({ mode: 'production', printUrl: false, surfaceContext: true, lanAddresses: [] }))
+    await ctx.plugin(SystemPrompt, { persona: '' })
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(log).not.toHaveBeenCalled()
+    const assembly = await ctx.systemPrompt.assemble()
+    expect(assembly.sections.find(entry => entry.name === 'app:web-surface')?.text)
+      .toContain('without `--dev`')
+    await ctx.fiber.dispose()
+  })
+
+  it('skips the surface context when disabled (the one-shot layer): no prompt section, no bash variables', async () => {
+    stageDist()
+    const ctx = new Context()
+    ctx.provide('httpServer', fakeHttpServer().server)
+    const contributions: BashContribution[] = []
+    ctx.provide('bashEnv', {
+      register: (contribution: BashContribution) => {
+        contributions.push(contribution)
+        return () => {}
+      },
+    } as never)
+    apply(ctx, new Config({ mode: 'production', printUrl: false, surfaceContext: false, lanAddresses: [] }))
+    await ctx.plugin(SystemPrompt, { persona: '' })
+    await new Promise(resolve => setTimeout(resolve, 0))
+    const assembly = await ctx.systemPrompt.assemble()
+    expect(assembly.sections.some(entry => entry.name === 'app:web-surface')).toBe(false)
+    expect(contributions).toEqual([])
+    await ctx.fiber.dispose()
+  })
+
+  it('prints the loopback-only URL line when no LAN snapshot exists', async () => {
+    stageDist()
+    const ctx = new Context()
+    ctx.provide('httpServer', fakeHttpServer().server)
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
+    apply(ctx, new Config({ mode: 'production', printUrl: true, surfaceContext: true, lanAddresses: [] }))
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(log).toHaveBeenCalledWith('dsh web: http://127.0.0.1:4567')
+    await ctx.fiber.dispose()
+  })
+
+  it('defers the URL line until Loader settlement and drops it when the server is gone', async () => {
+    stageDist()
+    // Settlement path: the line waits for loader.await() so supervisors can
+    // RPC immediately after observing it.
+    const settled = new Context()
+    settled.provide('httpServer', fakeHttpServer().server)
+    let release: () => void
+    const settlement = new Promise<void>((resolve) => { release = resolve })
+    settled.provide('loader', { await: () => settlement } as never)
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
+    apply(settled, new Config({ mode: 'production', printUrl: true, surfaceContext: true, lanAddresses: [] }))
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(log).not.toHaveBeenCalled()
+    release!()
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(log).toHaveBeenCalledWith('dsh web: http://127.0.0.1:4567')
+    await settled.fiber.dispose()
+
+    // Torn-down path: settlement resolves after the webserver is gone — no
+    // line, no crash.
+    log.mockClear()
+    const torn = new Context()
+    const child = torn.plugin((childCtx: Context) => {
+      childCtx.provide('httpServer', fakeHttpServer().server)
+    })
+    await child
+    let releaseTorn: () => void
+    const tornSettlement = new Promise<void>((resolve) => { releaseTorn = resolve })
+    torn.provide('loader', { await: () => tornSettlement } as never)
+    apply(torn, new Config({ mode: 'production', printUrl: true, surfaceContext: true, lanAddresses: [] }))
+    await child.dispose() // the httpServer service goes away
+    releaseTorn!()
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(log).not.toHaveBeenCalled()
+    await torn.fiber.dispose()
+  })
+
+  it('fails loud when the prompt section resolves against a portless webserver', async () => {
+    stageDist()
+    const ctx = new Context()
+    // A webserver whose bound port is gone (torn down mid-request): the
+    // section must throw, never render a URL with an undefined port.
+    const { server } = fakeHttpServer()
+    Object.defineProperty(server, 'port', { get: () => undefined })
+    ctx.provide('httpServer', server)
+    apply(ctx, new Config({ mode: 'production', printUrl: false, surfaceContext: true, lanAddresses: [] }))
+    await ctx.plugin(SystemPrompt, { persona: '' })
+    await new Promise(resolve => setTimeout(resolve, 0))
+    await expect(ctx.systemPrompt.assemble()).rejects.toThrow('httpServer service missing')
+    await ctx.fiber.dispose()
+  })
+
+  it('resolves the real built frontend dist through the package exports, failing loud unbuilt', () => {
+    // The production resolver (not the test seam). A built checkout resolves
+    // the frontend package's index.html; a dist-less one (the CI coverage
+    // lane runs before any build) must fail with the build hint, never a
+    // silent fallback.
+    try {
+      expect(originalResolve()).toMatch(/dist[/\\]index\.html$/)
+    } catch (error) {
+      expect((error as Error).message).toContain('frontend dist not built')
+    }
+  })
+})
--- a/packages/bundle/web-app/tsconfig.json
+++ b/packages/bundle/web-app/tsconfig.json
@@ -0,0 +1,33 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../host/frontend-static"
+    },
+    {
+      "path": "../../host/webserver"
+    },
+    {
+      "path": "../../core/system-prompt"
+    },
+    {
+      "path": "../../bash/bash-env"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}
--- a/packages/client/AGENTS.md
+++ b/packages/client/AGENTS.md
@@ -60,16 +60,16 @@ One UI feature = one plugin package (`src/client/` browser half). A multi-domain

 ## Styling

-[docs/web-styling.md](../../docs/web-styling.md) is authoritative. In short: design tokens live in `web-ui/src/style/global.css` (`:root` light values, `[data-theme='dark']` overrides); component CSS references tokens only — no literal color values. CSS Modules + `clsx`; no component library, no tailwind ([framework ruling](../../.agents/notes/implemented/process/2026-07-19-web-styling-system.md)). Product copy is Chinese; code comments are English.
+[docs/web-styling.md](../../docs/web-styling.md) is authoritative. Shared `--dsw-*` tokens and global sheets live in `ui-theme/src/styles/`; feature components consume semantic aliases through CSS Modules and `clsx`, with no literal colors, component library, or Tailwind. Product copy is Chinese; code comments are English.

 ## Testing and coverage

 The GUI test structure (three tiers, lane map) is settled in the [GUI testing system note](../../.agents/notes/implemented/process/2026-07-20-gui-testing-system.md); repo-wide policy in [docs/testing.md](../../docs/testing.md).

- **Both client packages are inside the per-file 100% coverage gate** (`pnpm run test:coverage`). `web-runtime` is covered by node-env object/protocol suites; `web-ui` rides the jsdom lane. Genuinely unreachable defensive arms take a `/* v8 ignore -- <reason> */` comment with a real reason, never a bare ignore.
- **web-ui specs are end-to-end behavior checks, not unit tests.** A jsdom spec renders the component with realistic props (or a driven fixture runtime) and asserts what the user would see — never class names, hook internals, or render counts. Components are consumables: behavior-shaped specs survive a rewrite, implementation-shaped specs don't.
- The jsdom environment comes from a per-file `// @vitest-environment jsdom` pragma on the spec's first line — the shared config stays node-env. Start a new spec from an existing one (`web-ui/tests/tool-card.spec.tsx` is a good template).
- **Each tier asserts its own layer.** Data-layer semantics (state machines, wire shapes, reference stability) belong to the `web-runtime` and `apiproxy` suites — don't re-assert them from component specs.
+- Client source packages are inside the per-file 100% coverage gate (`pnpm run test:coverage`). Genuinely unreachable defensive arms take a `/* v8 ignore -- <reason> */` comment with a real reason, never a bare ignore.
+- Component specs render with realistic props or a driven fixture runtime and assert user-visible behavior, not class names, hook internals, or render counts.
+- The jsdom environment comes from a per-file `// @vitest-environment jsdom` pragma on the spec's first line; the shared config stays node-env.
+- Each tier asserts its own layer. Data-layer semantics belong to the runtime and host suites; component specs cover presentation behavior.

 ## Before you push: the local check ladder

@@ -86,9 +86,9 @@ If `test:gui` is red on code you did not touch, neither silently fix nor ignore
 Bringing up a new `packages/client/<name>` plugin package (ui-workspace is the latest walked example; ui-sidebar/ui-question are good skeletons to copy):

 1. **Package skeleton**: `package.json` (`@deepseek-ai/dsh-client-<name>`, exports `.`/`./invariant`/`./client`/`./src/*`/`./package.json`, `dshClient` manifest, `files` list), `tsconfig.json` (extends `tsconfig.base.client.json`, one `references` entry per workspace dependency plus `support/invariants`), `tsdown.config.ts` (`clientBundle(id, ['lib/types/index.js', 'lib/types/invariant.js'])`), `src/index.ts` (empty node-half apply), `src/invariant.ts` (companion with a real reason), `src/css-modules.d.ts` when using CSS Modules, `README.md` with the Model Experience section.
-2. **Three registration surfaces, all required** (missing any one fails at a different, later point): the `tsconfig.client.json` aggregate `references` entry; a `dshClient` row in `apps/cli/config/web.cordis.yml`; an `apps/cli/package.json` dependency (Loader resolves each config-tree package against the composing app's URL — a row whose package is not an `apps/cli` dependency fails to import). `pnpm-workspace.yaml` already globs `packages/*/*`.
+2. **Three registration surfaces, all required** (missing any one fails at a different, later point): the `tsconfig.client.json` aggregate `references` entry; a `dshClient` row in `packages/bundle/web-app/cordis.patch.yml`; a `packages/bundle/web-app/package.json` dependency (profile boots resolve bare row names through the healed `$DSH_HOME/profiles/node_modules` fallback, which mirrors the app's and each bundle's declared dependencies — a row whose package no manifest declares fails to import). `pnpm-workspace.yaml` already globs `packages/*/*`.
 3. **dshClient manifest semantics**: `platform: 'web'` always; `immediately: true` only for stage-one-prefetch infrastructure rows. `inject` lists package-name dependency edges — they are **informational only** (preflight display, HMR diffing); they do not sequence entry activation or apply order. Activation order is cordis fiber inject waiting on *services*, nothing else.
-4. **Registering into another package's slot**: if the declaring host provides no waitable service, your apply's order relative to the host's is unconstrained — a bare `slots.register` into its slot races boot (intermittent `slot "..." is not declared` page failures). Register with declaration-aware deferral: check `ctx.slots.spec(name)`, otherwise `ctx.slots.subscribe(name)` and register on the declaration event (SlotCore supports subscribing ahead of declaration); make the registration idempotent, and unsubscribe + dispose in the effect disposer. Only take a service edge in `inject` when the host actually provides one (ui-question → `'conversation'` is that case).
+4. **Registering into another package's slot**: apply order is unconstrained, and a business service is not a declaration barrier. Use `ctx.slots.inject(name, () => ctx.slots.register(...))`; it waits on the actual declaration, removes the contribution when that declaration collapses, reruns after redeclaration, and leaves with the caller's plugin fiber. Return a generator yielding each registration when several contributions must install and roll back atomically. A bare `slots.register` into an undeclared slot remains an error; keep service edges only for services the contribution actually reads.
 5. Rebuild the bundle (`pnpm --filter <pkg> bundle`) before probing a live `dsh web` server — the registry serves `lib/client.js`, not sources.

 ## New component checklist
--- a/packages/client/README.i18n.yaml
+++ b/packages/client/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/client/README.md
-README.md: 31d884c04a8b0233713b77b82b3d9cc7052003ca
-README.zh.md: 9c95db529306519136d6d68758889350e5dd65e4
+README.md: b950772d4cad6d873426f8aee6416fa56afca2ee
+README.zh.md: 8f1f7f46777b7037e8baa04c9ec16ef74ffd478d
--- a/packages/client/README.md
+++ b/packages/client/README.md
@@ -2,33 +2,38 @@

 English | [中文](README.zh.md)

-The browser side of the dsh web GUI: shell kernel, module system, wire consumer, React-free object services, the slot system, and the `ui-*` feature-plugin roster. Authoring rules live in [AGENTS.md](AGENTS.md); the host half is [`host/`](../host/README.md). All **product** packages, named `@deepseek-ai/dsh-client-<name>`.
+The browser side of the dsh web GUI: shell boot, browser-host communication, shared UI services, and feature plugins. Authoring rules live in [AGENTS.md](AGENTS.md); the host half is [`host/`](../host/README.md). All except `test-runtime` are **product** packages named `@deepseek-ai/dsh-client-<name>`.

-| Package | Role | ctx key / slot |
-|---|---|---|
-| `web/` | Shell kernel: `AppWebEntry` runs the two-stage boot over the host-pushed entry graph | (boots the tree) |
-| `modules/` | Client module system: browser peer of Node's ESM loader as a lazy CJS table under the vendored cordis Loader | (module face) |
-| `web-react/` | Shell-side React glue: `createSlotRenderer` + `SessionProvider` render seats | (renderer install) |
-| `connection/` | Wire consumer both ends: browser `ctx.connection` (shared api client + stream loop) and the node half mounting the `/api` route with its browser-trust fence | `ctx.connection` |
-| `runtime/` | Client cordis boot and React-free object services: slots, Sessions, Workspaces, per-session bindings | `ctx.slots` `ctx.sessions` `ctx.workspaces` |
-| `hmr/` | Dev-only hot reload for script-loaded client plugins (`--dev` graphs) | (dev entry) |
-| `locale/` | Browser locale preference (`zh`/`en`) plus the ns×locale dictionary registry | `ctx.locale` |
-| `ui-slots/` | Slot registry pure core: SlotMap merging, single `register` API, the four-share props family | (types + core) |
-| `ui-theme/` | Theme preference over the `--dsw-*` token stylesheets (`light`/`dark`/`system`) | `ctx.theme` |
-| `ui-primitives/` | Pure React atoms: icons, Button/Pill/Menu/Modal/Input, markdown family | (component library) |
-| `ui-layout/` | Shell three-column AppFrame; declares `sidebar` / `conversation` / `details` / `conversation.empty` | `ctx.layout` |
-| `ui-sidebar/` | Sidebar shell: Workspace/session rail, search, collapse; declares `sidebar.workspaces` | (slot host) |
-| `ui-workspace/` | Shared Workspace picker: browser region + hero picker over the same creation flow | (fills `sidebar.workspaces`, `conversation.hero.workspace`) |
-| `ui-conversation/` | Conversation domain: skeleton, chat view, input dock, per-tool row slots | (slot host) |
-| `ui-trajectory/` | Trajectory/Waterfall view tabs; the minimal pure-consumer plugin exemplar | (fills `conversation.view`) |
-| `ui-command/` | Command surface: session-keyed directory cache, `/` source, three-kind dispatch | `ctx.command` |
-| `ui-slash/` | Input trigger pipeline: `/` and `@` detection, grouped candidate menu, source roster | `ctx.slash` |
-| `ui-skill/` | `/`-trigger skill reference source over the `skill.list` RPC | (registers into `ctx.slash`) |
-| `ui-subagent/` | `@`-trigger subagent reference source over the sessions snapshot | (registers into `ctx.slash`) |
-| `ui-model/` | Model selection: `/model` popupSelect + the composer model seat over `ModelService` | `ctx.models` |
-| `ui-question/` | Web `ask_user_question`: host half mounts the tool, browser half fills the composer seat | (fills `conversation.composer`) |
-| `ui-settings/` | Settings shell: trigger chrome + modal panel; declares the `settings.*` slots | (slot host) |
-| `ui-settings-general/` | Settings ownerless copy: chrome content + General section skeleton | (fills `settings.*`) |
-| `ui-models/` | Models settings nav entry (content column lands in a later phase) | (fills `settings.section`) |
+| Package | Purpose |
+|---|---|
+| [`web/`](web/README.md) | Boots the browser shell from the client entry graph. |
+| [`modules/`](modules/README.md) | Loads browser-side client modules. |
+| [`web-react/`](web-react/README.md) | Connects the shell runtime to React rendering. |
+| [`connection/`](connection/README.md) | Maintains browser-host RPC communication and event delivery. |
+| [`runtime/`](runtime/README.md) | Provides shared client services for sessions, workspaces, and UI composition. |
+| [`hmr/`](hmr/README.md) | Refreshes client plugins during development. |
+| [`locale/`](locale/README.md) | Provides localization preferences and message dictionaries. |
+| [`schema-form/`](schema-form/README.md) | Provides schema-backed draft handling for settings editors. |
+| [`test-runtime/`](test-runtime/README.md) | Provides shared repository test support for client feature packages. |
+| [`ui-slots/`](ui-slots/README.md) | Defines how UI features register and compose extension slots. |
+| [`ui-theme/`](ui-theme/README.md) | Applies the selected color theme. |
+| [`ui-primitives/`](ui-primitives/README.md) | Provides shared React controls, icons, and content renderers. |
+| [`ui-layout/`](ui-layout/README.md) | Arranges the main application regions. |
+| [`ui-sidebar/`](ui-sidebar/README.md) | Presents workspace and session navigation. |
+| [`ui-workspace/`](ui-workspace/README.md) | Provides workspace selection and creation surfaces. |
+| [`ui-conversation/`](ui-conversation/README.md) | Presents the active conversation and its input surface. |
+| [`ui-goal/`](ui-goal/README.md) | Presents and manages the current goal. |
+| [`ui-trajectory/`](ui-trajectory/README.md) | Presents alternate views of agent activity. |
+| [`ui-command/`](ui-command/README.md) | Provides session-aware command discovery and dispatch. |
+| [`ui-slash/`](ui-slash/README.md) | Coordinates inline command and reference suggestions. |
+| [`ui-skill/`](ui-skill/README.md) | Adds skill references to inline suggestions. |
+| [`ui-subagent/`](ui-subagent/README.md) | Provides subagent navigation, child transcript states, and inline references. |
+| [`ui-model/`](ui-model/README.md) | Provides model selection in conversation surfaces. |
+| [`ui-permission/`](ui-permission/README.md) | Configures default permissions and switches the current session's access. |
+| [`ui-plan/`](ui-plan/README.md) | Presents active plan-mode status and its exit control. |
+| [`ui-question/`](ui-question/README.md) | Presents interactive questions requested by the agent. |
+| [`ui-settings/`](ui-settings/README.md) | Hosts the settings interface and its extension areas. |
+| [`ui-settings-general/`](ui-settings-general/README.md) | Provides the general settings section. |
+| [`ui-models/`](ui-models/README.md) | Provides model-provider configuration and DeepSeek onboarding. |

-Feature UI composes only through the slot system (`ctx.slots.register`) — the [slot system standard](../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md) is the definitive model; the [web client architecture note](../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md) owns the loading chain and object layer.
+Each child reference owns its contract and detailed behavior. The [slot system standard](../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md) and [web client architecture note](../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md) own the cross-package composition and loading decisions.
--- a/packages/client/README.zh.md
+++ b/packages/client/README.zh.md
@@ -2,33 +2,38 @@

 [English](README.md) | 中文

-dsh web GUI 的浏览器侧：shell 内核、模块系统、协议消费层、无 React 依赖的对象服务、slot 系统，以及 `ui-*` 特性插件阵列。编写规则见 [AGENTS.md](AGENTS.md)；宿主半侧是 [`host/`](../host/README.md)。全部为**产品**包，命名为 `@deepseek-ai/dsh-client-<name>`。
+dsh web GUI 的浏览器侧：shell 启动、浏览器与宿主通信、共享 UI 服务和特性插件。编写规则见 [AGENTS.md](AGENTS.md)；宿主半侧是 [`host/`](../host/README.md)。除 `test-runtime` 外，均为命名成 `@deepseek-ai/dsh-client-<name>` 的**产品**包。

-| 包 | 角色 | ctx 键／slot |
-|---|---|---|
-| `web/` | shell 内核：`AppWebEntry` 基于宿主推送的条目图运行两阶段启动 | （启动整棵树） |
-| `modules/` | 客户端模块系统：Node ESM 加载器的浏览器对等物，是 vendored cordis Loader 之下的惰性 CJS 表 | （模块面） |
-| `web-react/` | shell 侧 React 胶水：`createSlotRenderer` + `SessionProvider` 渲染座位 | （渲染器安装） |
-| `connection/` | 协议两端的消费者：浏览器侧 `ctx.connection`（共享 api 客户端 + 流循环），node 半侧挂载带浏览器信任栅栏的 `/api` 路由 | `ctx.connection` |
-| `runtime/` | 客户端 cordis 启动与无 React 对象服务：slots、Session、Workspace、逐会话绑定 | `ctx.slots` `ctx.sessions` `ctx.workspaces` |
-| `hmr/` | 仅开发用的外部脚本加载型客户端插件热重载（`--dev` 图） | （开发条目） |
-| `locale/` | 浏览器语言偏好（`zh`／`en`）与 ns×locale 词典注册表 | `ctx.locale` |
-| `ui-slots/` | slot 注册表纯核心：SlotMap 合并、单一 `register` API、四份额 props 族 | （类型 + 核心） |
-| `ui-theme/` | 基于 `--dsw-*` token 样式表的主题偏好（`light`／`dark`／`system`） | `ctx.theme` |
-| `ui-primitives/` | 纯 React 原子：图标、Button/Pill/Menu/Modal/Input、markdown 族 | （组件库） |
-| `ui-layout/` | shell 三栏 AppFrame；声明 `sidebar`／`conversation`／`details`／`conversation.empty` | `ctx.layout` |
-| `ui-sidebar/` | 侧栏 shell：Workspace/会话栏、搜索、折叠；声明 `sidebar.workspaces` | （slot 宿主） |
-| `ui-workspace/` | 共享 Workspace 选择器：浏览区域 + hero 选择器共用同一创建流程 | （填充 `sidebar.workspaces`、`conversation.hero.workspace`） |
-| `ui-conversation/` | 会话域：骨架、聊天视图、输入坞、逐工具行 slot | （slot 宿主） |
-| `ui-trajectory/` | Trajectory／Waterfall 视图标签；最小纯消费者插件范例 | （填充 `conversation.view`） |
-| `ui-command/` | 命令面：按会话键控的目录缓存、`/` 源、三类分发 | `ctx.command` |
-| `ui-slash/` | 输入触发流水线：光标下的 `/` 与 `@` 检测、分组候选菜单、源名册 | `ctx.slash` |
-| `ui-skill/` | 基于 `skill.list` RPC 的 `/` 触发技能引用源 | （注册进 `ctx.slash`） |
-| `ui-subagent/` | 基于会话快照的 `@` 触发子代理引用源 | （注册进 `ctx.slash`） |
-| `ui-model/` | 模型选择：`/model` popupSelect + 输入坞模型座位，均由 `ModelService` 驱动 | `ctx.models` |
-| `ui-question/` | Web `ask_user_question`：宿主半侧挂载工具，浏览器半侧填充输入坞座位 | （填充 `conversation.composer`） |
-| `ui-settings/` | 设置 shell：触发 chrome + 模态面板；声明 `settings.*` slot | （slot 宿主） |
-| `ui-settings-general/` | 设置的无主文案：chrome 内容 + General 分区骨架 | （填充 `settings.*`） |
-| `ui-models/` | 模型设置导航项（内容列留待后续阶段） | （填充 `settings.section`） |
+| 包 | 目的 |
+|---|---|
+| [`web/`](web/README.md) | 从客户端条目图启动浏览器 shell。 |
+| [`modules/`](modules/README.md) | 加载浏览器侧客户端模块。 |
+| [`web-react/`](web-react/README.md) | 连接 shell 运行时与 React 渲染。 |
+| [`connection/`](connection/README.md) | 维护浏览器与宿主之间的 RPC 通信和事件传递。 |
+| [`runtime/`](runtime/README.md) | 为会话、Workspace 和 UI 组合提供共享客户端服务。 |
+| [`hmr/`](hmr/README.md) | 在开发期间刷新客户端插件。 |
+| [`locale/`](locale/README.md) | 提供本地化偏好与消息词典。 |
+| [`schema-form/`](schema-form/README.md) | 为设置编辑器提供 schema 驱动的草稿处理。 |
+| [`test-runtime/`](test-runtime/README.md) | 为客户端特性包提供共享的仓库测试支持。 |
+| [`ui-slots/`](ui-slots/README.md) | 定义 UI 特性注册和组合扩展 slot 的方式。 |
+| [`ui-theme/`](ui-theme/README.md) | 应用所选颜色主题。 |
+| [`ui-primitives/`](ui-primitives/README.md) | 提供共享 React 控件、图标和内容渲染器。 |
+| [`ui-layout/`](ui-layout/README.md) | 排列应用的主要区域。 |
+| [`ui-sidebar/`](ui-sidebar/README.md) | 展示 Workspace 与会话导航。 |
+| [`ui-workspace/`](ui-workspace/README.md) | 提供 Workspace 选择与创建界面。 |
+| [`ui-conversation/`](ui-conversation/README.md) | 展示当前会话及其输入界面。 |
+| [`ui-goal/`](ui-goal/README.md) | 展示和管理当前目标。 |
+| [`ui-trajectory/`](ui-trajectory/README.md) | 提供 agent（智能体）活动的其他视图。 |
+| [`ui-command/`](ui-command/README.md) | 提供会话感知的命令发现与分发。 |
+| [`ui-slash/`](ui-slash/README.md) | 协调内联命令和引用建议。 |
+| [`ui-skill/`](ui-skill/README.md) | 向内联建议添加 skill（技能）引用。 |
+| [`ui-subagent/`](ui-subagent/README.md) | 提供 subagent 导航、子会话记录状态和内联引用。 |
+| [`ui-model/`](ui-model/README.md) | 在会话界面中提供模型选择。 |
+| [`ui-permission/`](ui-permission/README.md) | 配置默认权限并切换当前会话的访问模式。 |
+| [`ui-plan/`](ui-plan/README.md) | 展示生效中的 plan mode 状态及其退出控件。 |
+| [`ui-question/`](ui-question/README.md) | 展示 agent 请求的交互式问题。 |
+| [`ui-settings/`](ui-settings/README.md) | 承载设置界面及其扩展区域。 |
+| [`ui-settings-general/`](ui-settings-general/README.md) | 提供常规设置分区。 |
+| [`ui-models/`](ui-models/README.md) | 提供模型提供方配置与 DeepSeek 配置引导。 |

-特性 UI 只通过 slot 系统组合（`ctx.slots.register`）——[slot 系统标准](../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md)是权威模型；[web 客户端架构 Note](../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md) 拥有加载链与对象层。
+每个子文档负责自身的契约和详细行为。[slot 系统标准](../../.agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md)与 [Web 客户端架构 Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md)负责跨包组合与加载决策。
--- a/packages/client/connection/README.i18n.yaml
+++ b/packages/client/connection/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/client/connection/README.md
-README.md: faf093964a740092983e13bf88f2cccd853c3e36
-README.zh.md: b06ab245dedbde13957aa416be044ef107b2753c
+README.md: 1393e79aacecbbf7b186f19e4c42269595854b0e
+README.zh.md: 70380ceba1b16b2970e947fb6cd9b2af9085ae51
--- a/packages/client/connection/README.md
+++ b/packages/client/connection/README.md
@@ -2,20 +2,16 @@

 English | [中文](README.zh.md)

-Wire consumer layer: the client plugin's apply mounts `ctx.connection` (shared api client + current-page loopback state + single-consumer stream-loop starter); the export face carries the wire contract types, the `AbstractApiClient` seam, and the loop's sink/config types. The real browser carrier uses HTTP POST for unary and respond operations and opens one downlink-only WebSocket each for `events.mux` and `events.host`; the fixture and in-process carriers continue to satisfy the same two-stream abstraction. Loopback hostname classification stays package-internal: the `/api` Host fence and WebSocket upgrades use it directly, while other client plugins consume the derived `ctx.connection.isLoopback` state. The node half's `/api` route pins the privileged method set (`host.pickDirectory`, `host.openPath`, and the whole configuration plane — `settings.describe`/`update`/`replace`/`mutate` and `credentials.describe`/`set`/`unset`, reads included, since describing returns the exposed configuration and probing an arbitrary reference reports where a credential comes from) to loopback by passing the trust fence with an empty trust list — a declared `trustedHosts` authority reaches every other method, while these stay loopback-local until a real authentication layer exists. The platform subclasses (WebApiClient/FixtureApiClient), the ConnectionController loop, and the fixture data source are package-internal — apply selects and drives them; tests reach them via src. The downlink boundary is documented in the [WebSocket downlink carrier Agent Note](../../../.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md); the protocol contract is api-contracts v3 §3.
+Wire consumer layer: the client plugin's apply mounts `ctx.connection` (shared api client + current-page loopback state + single-consumer stream-loop starter); the export face carries the wire contract types, the `AbstractApiClient` seam, and the loop's sink/config types. The browser carrier uses HTTP POST for unary and respond operations and opens one downlink-only WebSocket each for `events.mux` and `events.host`; the in-process carrier satisfies the same two-stream abstraction. Loopback hostname classification stays package-internal: the `/api` Host fence and WebSocket upgrades use it directly, while other client plugins consume the derived `ctx.connection.isLoopback` state. The node half's `/api` route pins the privileged method set (`host.pickDirectory`, `host.openPath`, and the whole configuration plane — `settings.describe`/`openDocument`/`update`/`replace`/`mutate` and `credentials.describe`/`set`/`unset`; reads and native actions included, since describing returns the exposed configuration, opening acts on the Host desktop, and probing an arbitrary reference reports where a credential comes from) to loopback by passing the trust fence with an empty trust list — a declared `trustedHosts` authority reaches every other method, while these stay loopback-local until a real authentication layer exists. The platform carriers and ConnectionController loop are package-internal; apply selects and drives them. The downlink boundary is documented in the [WebSocket downlink carrier Agent Note](../../../.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md); the protocol contract is api-contracts v3 §3.

 ## /api browser-trust fence

-The node half guards every entry under `/api` before bridging or upgrading (`src/api-request-trust.ts`). Every request — browser-marked or not — must present a `Host` that is a loopback authority or matches a `trustedHosts` entry: exact on `host:port` entries, any port on port-less entries, both sides compared through WHATWG normalization (DNS-rebinding defense). There is deliberately no shortcut for unmarked HTTP requests: over plain HTTP a browser attaches neither `Origin` nor Fetch-Metadata to image and navigation reads, so an unmarked request may still be a rebound browser read with a readable response, and Host is the one header rebinding cannot forge; a browser WebSocket handshake carries `Origin` and passes the same comparison. Non-browser clients pass the same fence via loopback, the CLI-derived LAN IP literals, or a declared authority. When markers are present, an attached `Origin` must equal the Host authority, and an explicit `sec-fetch-site: cross-site` marker is refused. A `trustedHosts` entry that is not a bare, canonical `host[:port]` authority — one WHATWG parsing reads back exactly as written — fails the plugin load loudly: parsing would otherwise quietly authorize the hostname inside `harness.internal/path`, or broaden a dangling-colon or zero-padded port to an any-port grant. HTTP failures answer plain 403 before any RPC dispatch; upgrade failures reject the handshake before any event stream starts. A non-loopback (`--host 0.0.0.0`) deployment therefore needs its serving authorities trusted: the dsh CLI derives the machine's LAN IP literals itself and its `--trusted-host` flag declares named ones, so `trustedHosts` in cordis.yml is for compositions the CLI does not boot. The fence is deliberately not an authentication layer — reachability policy stays with the webserver binding, and auth remains deferred work. Decision record: [the api browser-trust boundary Agent Note](../../../.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.md).
+The node half guards every entry under `/api` before bridging or upgrading (`src/api-request-trust.ts`). Every request — browser-marked or not — must present a `Host` that is a loopback authority or matches a `trustedHosts` entry: exact on `host:port` entries, any port on port-less entries, both sides compared through WHATWG normalization (DNS-rebinding defense). There is deliberately no shortcut for unmarked HTTP requests: over plain HTTP a browser attaches neither `Origin` nor Fetch-Metadata to image and navigation reads, so an unmarked request may still be a rebound browser read with a readable response, and Host is the one header rebinding cannot forge; a browser WebSocket handshake carries `Origin` and passes the same comparison. Non-browser clients pass the same fence via loopback, the CLI-derived LAN IP literals, or a declared authority. When markers are present, an attached `Origin` must equal the Host authority, and an explicit `sec-fetch-site: cross-site` marker is refused. A `trustedHosts` entry that is not a bare, canonical `host[:port]` authority — one WHATWG parsing reads back exactly as written — fails the plugin load loudly: parsing would otherwise quietly authorize the hostname inside `harness.internal/path`, or broaden a dangling-colon or zero-padded port to an any-port grant. HTTP failures answer plain 403 before any RPC dispatch; upgrade failures reject the handshake before any event stream starts. A non-loopback (`--host 0.0.0.0`) deployment therefore needs its serving authorities trusted: the dsh CLI derives the machine's LAN IP literals itself and its `--trusted-host` flag declares named ones, so `trustedHosts` in cordis.yml is for compositions the CLI does not boot. The fence is a reachability policy, not authentication; the Web carrier provides no authentication layer. Decision record: [the api browser-trust boundary Agent Note](../../../.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.md).

 ## `/api` WebSocket downlinks

 `/api/events.mux` and `/api/events.host` each accept a WebSocket upgrade and send only the corresponding `ServerRequest` text messages to the browser; the client sends no application data over these sockets. If either socket ends, the current connection generation fails and rebuilds both streams; readiness still requires both sockets to be open and the `host.describe` HTTP call to succeed. Host teardown terminates both sockets, aborts their sources, and waits for source cleanup before returning. Ordinary network GETs to these paths return 426 with no SSE fallback; `toFetchHandler`'s SSE codec serves only the isomorphic in-process carrier.

-## Keyless fixture
-
-Any `fixture` query parameter selects the in-memory carrier. `fixture=empty` starts with no Workspace or Session; `fixturePrompt=reject` rejects prompts before acceptance; `fixtureAttach=fail` publishes a Session but rejects its Workspace attachment; `fixtureSessionCreate=drop-response` publishes and frames a Session before dropping the create response; and `fixtureFrames=workspace-first` reverses the default session-first create-frame order. Workspace creation by name/path and caller-preallocated SessionIds remain deterministic enough for assembled Web tests to reconcile list and frame arrival. Fixture content search preserves the production-facing `unicode61`-style case, diacritic, and token-phrase behavior and returns a match-centered snippet of at most 120 Unicode code points.
-
 ## Model Experience

 None, as the wire consumer layer moves already-composed messages between browser and host; nothing here reaches a model request.
@@ -26,5 +22,4 @@ None; this package neither assembles nor sends a provider request.

 ## Known Limitations and Deferred Work

- **history's implicit resume is arguable** — opening history on an unattached session pulls an agent up host-side; the pure-persistence-read alternative is recorded in the rt-core reconciliation ledger, unchanged in P-I. This package's consumers see it as latency on first open.
- **`ToolEventView`/`ToolCallView`/`ToolResultView` re-exports are scheduled for removal** — they fall when the toolview migration deletes the host `viewFor` line (presentation belongs to the client); the fixture keeps a local `viewFor` mirror until then.
+- **History resumes an unattached session** — opening history may create the host-side agent and add latency to the first open; there is no persistence-only read path.
--- a/packages/client/connection/README.zh.md
+++ b/packages/client/connection/README.zh.md
@@ -2,20 +2,16 @@

 [English](README.md) | 中文

-协议消费层：客户端插件的 apply 会挂载 `ctx.connection`（共享 API 客户端 + 当前页面的 loopback 状态 + 单消费方流循环启动器）；导出表层携带协议契约类型、`AbstractApiClient` seam，以及循环的 sink／配置类型。真实浏览器载体以 HTTP POST 发送 unary／respond，并为 `events.mux` 与 `events.host` 各开一条只下行的 WebSocket；fixture 与进程内载体继续满足同一双流抽象。Loopback hostname 判定逻辑留在包内部：`/api` Host fence 与 WebSocket upgrade 会直接使用它，其他客户端插件则消费派生的 `ctx.connection.isLoopback` 状态。node 半侧的 `/api` 路由让特权方法集（`host.pickDirectory`、`host.openPath`，以及整个配置面——`settings.describe`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`，读取也在内，因为 describe 会返回已暴露的配置，而探测任意引用会报出某条凭据来自何处）以空信任表过信任 fence，从而钉在回环——已声明的 `trustedHosts` 授权可达其余全部方法，而这些方法在真正的认证层出现之前仍只限回环本机。平台子类（WebApiClient/FixtureApiClient）、ConnectionController 循环和 fixture 数据源都属于包内部：apply 负责选择并驱动它们，测试则通过 src 访问。下行边界见 [WebSocket 下行载体 Agent Note](../../../.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md)；协议契约见 api-contracts v3 §3。
+协议消费层：客户端插件的 apply 会挂载 `ctx.connection`（共享 API 客户端 + 当前页面的 loopback 状态 + 单消费方流循环启动器）；导出表层携带协议契约类型、`AbstractApiClient` seam，以及循环的 sink／配置类型。浏览器载体以 HTTP POST 发送 unary／respond，并为 `events.mux` 与 `events.host` 各开一条只下行的 WebSocket；进程内载体满足同一双流抽象。Loopback hostname 判定逻辑留在包内部：`/api` Host fence 与 WebSocket upgrade 会直接使用它，其他客户端插件则消费派生的 `ctx.connection.isLoopback` 状态。node 半侧的 `/api` 路由让特权方法集（`host.pickDirectory`、`host.openPath`，以及整个配置面——`settings.describe`/`openDocument`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`；读取与原生操作也在内，因为 describe 会返回已暴露的配置、打开操作会作用于 Host 桌面，而探测任意引用会报出某条凭据来自何处）以空信任表过信任 fence，从而钉在回环——已声明的 `trustedHosts` 授权可达其余全部方法，而这些方法在真正的认证层出现之前仍只限回环本机。平台载体与 ConnectionController 循环属于包内部；apply 负责选择并驱动它们。下行边界见 [WebSocket 下行载体 Agent Note](../../../.agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.md)；协议契约见 api-contracts v3 §3。

 ## /api 浏览器信任栅栏

-node 半侧在桥接或 upgrade 前守卫 `/api` 下的每个入口（`src/api-request-trust.ts`）。每个请求——无论是否带浏览器标记——`Host` 都必须是回环地址权威，或与某个 `trustedHosts` 条目匹配：带端口的 `host:port` 条目精确匹配，不带端口的条目匹配任意端口，两侧均经 WHATWG 归一化后比较（DNS rebinding 防御）。刻意不为无浏览器标记的 HTTP 请求开捷径：明文 HTTP 下浏览器的图片与导航读取既不带 `Origin` 也不带 Fetch-Metadata，因此无标记请求仍可能是被重绑页面发起的、响应可被读走的读取，而 Host 是重绑唯一伪造不了的请求头；WebSocket 浏览器握手会带 `Origin` 并通过同一道比较。非浏览器客户端经由回环地址、CLI 推导的 LAN IP 字面量或已声明的权威通过同一道栅栏。当标记存在时，`Origin` 必须与 Host 权威完全一致；显式的 `sec-fetch-site: cross-site` 标记一律拒绝。不是纯的、规范形 `host[:port]` 权威的 `trustedHosts` 条目——即 WHATWG 解析读回后与原文不完全一致的——会让插件加载大声失败：否则解析会悄悄授权 `harness.internal/path` 这类笔误里的 hostname，或把悬空冒号、补零端口放大成任意端口授权。HTTP 失败在任何 RPC 分发之前以纯 403 应答，upgrade 失败在启动任何 event stream 前拒绝握手。因此非回环（`--host 0.0.0.0`）部署需要让自己的服务权威被信任：dsh CLI 会自行推导本机的 LAN IP 字面量，其 `--trusted-host` flag 用于声明具名权威，所以 cordis.yml 中的 `trustedHosts` 面向 CLI 不参与引导的组合。这道栅栏刻意不承担认证职责——可达性策略归 webserver 绑定配置，认证仍是延期工作。决策记录：[api 浏览器信任边界 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.md)。
+node 半侧在桥接或 upgrade 前守卫 `/api` 下的每个入口（`src/api-request-trust.ts`）。每个请求——无论是否带浏览器标记——`Host` 都必须是回环地址权威，或与某个 `trustedHosts` 条目匹配：带端口的 `host:port` 条目精确匹配，不带端口的条目匹配任意端口，两侧均经 WHATWG 归一化后比较（DNS rebinding 防御）。刻意不为无浏览器标记的 HTTP 请求开捷径：明文 HTTP 下浏览器的图片与导航读取既不带 `Origin` 也不带 Fetch-Metadata，因此无标记请求仍可能是被重绑页面发起的、响应可被读走的读取，而 Host 是重绑唯一伪造不了的请求头；WebSocket 浏览器握手会带 `Origin` 并通过同一道比较。非浏览器客户端经由回环地址、CLI 推导的 LAN IP 字面量或已声明的权威通过同一道栅栏。当标记存在时，`Origin` 必须与 Host 权威完全一致；显式的 `sec-fetch-site: cross-site` 标记一律拒绝。不是纯的、规范形 `host[:port]` 权威的 `trustedHosts` 条目——即 WHATWG 解析读回后与原文不完全一致的——会让插件加载大声失败：否则解析会悄悄授权 `harness.internal/path` 这类笔误里的 hostname，或把悬空冒号、补零端口放大成任意端口授权。HTTP 失败在任何 RPC 分发之前以纯 403 应答，upgrade 失败在启动任何 event stream 前拒绝握手。因此非回环（`--host 0.0.0.0`）部署需要让自己的服务权威被信任：dsh CLI 会自行推导本机的 LAN IP 字面量，其 `--trusted-host` flag 用于声明具名权威，所以 cordis.yml 中的 `trustedHosts` 面向 CLI 不参与引导的组合。这道栅栏是可达性策略，而不是认证；Web 载体不提供认证层。决策记录：[api 浏览器信任边界 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-28-api-browser-trust-boundary.md)。

 ## `/api` WebSocket 下行

 `/api/events.mux` 与 `/api/events.host` 各接受一条 WebSocket upgrade，并只向浏览器发送对应的 `ServerRequest` text message；客户端不会在这些 socket 上发送业务数据。任一 socket 结束都会使当前 connection generation 失败并重建两条流，连接就绪仍要求两条 socket open 且 `host.describe` HTTP 调用成功。Host teardown 会终止两条 socket、中止各自的 source，并等待 source 清理完成后再返回。普通网络 GET 这些路径会返回 426，不保留 SSE 回退；`toFetchHandler` 的 SSE 编解码只服务进程内同构载体。

-## 无密钥 fixture
-
-任何 `fixture` 查询参数都会选择内存载体。`fixture=empty` 启动时不含 Workspace 或 Session；`fixturePrompt=reject` 在接受前拒绝提示词；`fixtureAttach=fail` 发布 Session 但拒绝将其附加到 Workspace；`fixtureSessionCreate=drop-response` 在丢弃创建响应前发布 Session 并为其发出帧；`fixtureFrames=workspace-first` 则反转默认的 Session 优先创建帧顺序。按名称／路径创建 Workspace 以及由调用方预先分配 SessionId，均具有足够的确定性，组装后的 Web 测试可以据此协调列表与帧的到达。fixture 内容搜索会保留面向生产环境的 `unicode61` 式大小写、变音符号和 token／短语行为，并返回以匹配位置为中心、最多包含 120 个 Unicode 码点的 snippet。
-
 ## 模型体验

 无。协议消费层只在浏览器与主机之间搬运已经组合好的消息；这里没有任何内容进入模型请求。
@@ -26,5 +22,4 @@ node 半侧在桥接或 upgrade 前守卫 `/api` 下的每个入口（`src/api-r

 ## 已知限制与暂缓事项

- **history 的隐式恢复存在争议**：在未附加的会话上打开 history，会在主机侧拉起 agent；纯持久化读取的替代方案记录在 rt-core 协调账本中，P-I 不作改变。该包的消费方会在首次打开时感受到这段延迟。
- **计划移除 `ToolEventView`／`ToolCallView`／`ToolResultView` 的重新导出**：当 toolview 迁移删除主机 `viewFor` 行时，它们会一并移除（呈现属于客户端）；在此之前，fixture 保留一份局部 `viewFor` 镜像。
+- **History 会恢复未附加的会话**：打开 history 可能创建宿主侧 agent，并增加首次打开的延迟；没有仅从持久化读取的路径。
--- a/packages/client/connection/package.json
+++ b/packages/client/connection/package.json
@@ -41,9 +41,7 @@
    "lib/index.js",
    "lib/invariant.js",
    "lib/client.js",
-    "lib/types/**/*.d.ts",
-    "lib/types/**/*.d.ts.map",
-    "src"
+    "lib/types/**/*.d.ts"
  ],
  "peerDependencies": {
    "@deepseek-ai/dsh-host-webserver": "^0.0.1",
--- a/packages/client/connection/src/client/api.ts
+++ b/packages/client/connection/src/client/api.ts
@@ -12,10 +12,10 @@ export type {
  WorkspaceApi, WorkspaceId, WorkspaceView,
  CommandsApi, CommandDescriptor, SkillsApi, SkillEntry,
  ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
-  InboxItemId, ModelReasoningEffort, ModelTarget, QueueAction, QueuedInboxItem, SessionModels,
+  ModelReasoningEffort, ModelTarget, QueueAction, QueuedInboxItem, SessionModels,
  GoalsApi, GoalRef,
  SettingsApi, SettingsNamespaceView, SettingsPathOpView, SettingsSecretView,
-  CredentialsApi, CredentialView, ConfigurableProviderView, LlmApi,
+  CredentialsApi, CredentialView, ConfigurableProviderView, DiscoveredModelView, LlmApi,
  SubagentsApi, SubagentAddress, SubagentCatalog, SubagentListEntry, SubagentPromptReceipt,
 } from '@deepseek-ai/dsh-host-apiproxy/api'
 export type { ToolCallView, ToolResultView } from '@deepseek-ai/dsh-tools/presentation'
@@ -34,6 +34,7 @@ export {
 export { AbstractApiClient } from '@deepseek-ai/dsh-host-apiproxy/client'
 export type { IApiClient } from '@deepseek-ai/dsh-host-apiproxy/client'
 export type { SessionId, SessionEvent } from '@deepseek-ai/dsh-session/types'
+export type { MessageId } from '@deepseek-ai/dsh-llm/brand'
 export type { ContentBlock, StreamChunk } from '@deepseek-ai/dsh-llm/types'

 import type { RpcResponse, RpcResult } from '@deepseek-ai/dsh-host-apiproxy/api'
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -27,7 +27,7 @@ import type {
 // Type-only: the brand constructor is host-side; the fixture casts at its
 // wire-fabrication boundary (the schema layer's one-cast-point posture).
 import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
-import { foldSurface } from '@deepseek-ai/dsh-session/surface'
+import { deriveEventMessage, foldSurface } from '@deepseek-ai/dsh-session/surface'
 import type {
  ApiProxy, ClientRequest, ClientResponse, HistoryEntry, HostFrame, MuxFrame, RpcReceipt,
  ModelProviderGroup, ModelTarget, RpcRequest, RpcResponse, RpcResult, ServerRequest, ServerResponse, SessionSummary,
@@ -167,7 +167,7 @@ const SEARCH_MATCHES_FIXTURE: { path: string; matches: { lineNumber: number; lin
      { lineNumber: 33, line: 'export function SearchRow({ toolName, block, inspect, t }: SearchRowProps) {' },
      { lineNumber: 35, line: '  const search = searchCardModel(block)' },
      { lineNumber: 52, line: '      search={search}' },
-      { lineNumber: 73, line: "    ctx.slots.register({ name: 'conversation.chat.toolview', key: 'grep', locale: NS }, SearchRow)" },
+      { lineNumber: 78, line: "      yield ctx.slots.register({ name: 'conversation.chat.toolview', key: 'grep', locale: NS }, SearchRow)" },
    ],
  },
 ]
@@ -339,7 +339,7 @@ function fixtureUsage(turn: number, step: number): TokenUsage {
 }

 /** fx-alpha history script: 60 turns (~130+ messages -> 3 pages at PAGE_MESSAGES=50),
- *  mixing reasoning blocks / tool call+result / steering / context. */
+ *  mixing reasoning blocks / tool call+result / context. */
 function buildAlphaLog(): SessionEvent[] {
  const events: Record<string, unknown>[] = []
  let time = Date.now() - 3_600_000
@@ -358,8 +358,14 @@ function buildAlphaLog(): SessionEvent[] {
    events.push({ seq, time: (time += 800), ...authored })
    return seq
  }
+  // This resident history represents completed model requests, so retain the
+  // route capacity that accompanied them just as the live prompt path does.
+  push({
+    type: 'request/context',
+    data: { provider: 'deepseek-official', model: 'deepseek-v4-flash', contextWindow: 128_000 },
+  })
  for (let turn = 0; turn < 60; turn++) {
-    push({ type: 'turn/start', data: { turn, trigger: { kind: 'message', source: { kind: 'user' } } } })
+    push({ type: 'turn/start', data: { turn } })
    const userSeq = push({
      type: 'user/message', surfaceOp: 'append',
      data: userMessage(text(turn === 59 ? USER_MARKDOWN_LITERAL : `问题 ${turn}：fixture 历史消息，用于翻页与渲染验收。`)),
@@ -393,9 +399,6 @@ function buildAlphaLog(): SessionEvent[] {
      push({ type: 'assistant/message', surfaceOp: 'append', data: { turn, step: 0, message: assistantMessage(blocks) } })
      push({ type: 'step/end', data: { turn, step: 0 } })
    }
-    if (turn % 13 === 6) {
-      push({ type: 'steering/message', surfaceOp: 'append', data: { turn, message: userMessage(text(`插话 ${turn}：fixture steering 消息。`)) } })
-    }
    push({ type: 'turn/end', data: { turn, reason: { kind: 'completed' } } })
  }
  // Three view-sample turns (60-62) cover the built-in card types. The real filesystem names in
@@ -403,7 +406,7 @@ function buildAlphaLog(): SessionEvent[] {
  // stays presenter-less as the unknown fallback.
  const toolTurn = (turn: number, name: string, args: string, resultText: string): void => {
    const callId = `fx-call-${turn}`
-    push({ type: 'turn/start', data: { turn, trigger: { kind: 'message', source: { kind: 'user' } } } })
+    push({ type: 'turn/start', data: { turn } })
    push({ type: 'user/message', surfaceOp: 'append', data: userMessage(text(`问题 ${turn}：${name} 样本。`)) })
    push({ type: 'step/start', data: { turn, step: 0 } })
    push({
@@ -440,7 +443,7 @@ function buildAlphaLog(): SessionEvent[] {
      + 'await tools.read({ file_path: "notes/missing.txt" }).catch(() => "tolerated")\n'
      + 'return { listing, demo }'
    const args = JSON.stringify({ code: program, description: 'Read the notes files and summarize' })
-    push({ type: 'turn/start', data: { turn, trigger: { kind: 'message', source: { kind: 'user' } } } })
+    push({ type: 'turn/start', data: { turn } })
    push({ type: 'user/message', surfaceOp: 'append', data: userMessage(text(`问题 ${turn}：run_code 样本。`)) })
    push({ type: 'step/start', data: { turn, step: 0 } })
    push({
@@ -685,7 +688,7 @@ function viewFor(event: SessionEvent, log: readonly SessionEvent[]): ToolEventVi
 * Fixture parallel of the plan unit's double-event fold: `command/run`
 * records named `plan` set the wanted target (`off` → false, else true);
 * `plan/mode` commits and clears it. `wanted` is exposed for the prompt
- * boundary (the fixture's agent/step parallel).
+ * boundary (the fixture's step/start parallel).
 */
 function foldPlan(log: readonly SessionEvent[]): { active: boolean; pending: boolean; wanted: boolean | null } {
  let active = false
@@ -822,6 +825,62 @@ interface FixtureRequestContext {
  contextWindow?: number
 }

+interface FixtureContextBreakdownProjection {
+  systemTokens: number
+  toolsTokens: number
+  messageTokens: number
+}
+
+/** Fixed token-meter heuristic constants mirrored by this client-only fixture. */
+const CHARS_PER_TOKEN = 4
+const BLOCK_OVERHEAD = 4
+const ROLE_OVERHEAD = 4
+
+/** Price fixture content with token-meter's fixed-density heuristic. */
+function estimateFixtureContent(blocks: readonly ContentBlock[]): number {
+  const densityPrice = (value: string): number => Math.ceil(value.length / CHARS_PER_TOKEN)
+  return blocks.reduce((tokens, block) => {
+    if (block.type === 'text' || block.type === 'reasoning') {
+      return tokens + densityPrice(block.text) + BLOCK_OVERHEAD
+    }
+    if (block.type === 'tool-call') {
+      return tokens + densityPrice(block.name) + densityPrice(block.arguments) + BLOCK_OVERHEAD
+    }
+    // ContentBlockMap is merge-extensible: this client graph sees only the
+    // base four members, but fixture turns do carry extended blocks at
+    // runtime, so the structural JSON fallback below is live code.
+    // oxlint-disable-next-line typescript/no-unnecessary-condition -- the type collapses without the out-of-graph merges (see above).
+    if (block.type === 'tool-result') {
+      return tokens + estimateFixtureContent(block.content) + BLOCK_OVERHEAD
+    }
+    return tokens + densityPrice(JSON.stringify(block)) + BLOCK_OVERHEAD
+  }, 0)
+}
+
+/** Fixture parallel of token-meter's heuristic context-composition projection. */
+function contextBreakdownOf(log: readonly SessionEvent[]): FixtureContextBreakdownProjection {
+  const headerEvent = log.findLast(event => event.type === 'request/header')
+  const header = headerEvent === undefined
+    ? undefined
+    : headerEvent.data.header
+  let messageTokens = 0
+  for (const seq of foldSurface(log).nodes) {
+    const event = log[seq]
+    if (event === undefined) continue
+    const message = deriveEventMessage(event)
+    if (message !== null) messageTokens += estimateFixtureContent(message.content) + ROLE_OVERHEAD
+  }
+  return {
+    systemTokens: header?.system === undefined
+      ? 0
+      : Math.ceil(header.system.length / CHARS_PER_TOKEN) + ROLE_OVERHEAD,
+    toolsTokens: header?.tools === undefined || header.tools.length === 0
+      ? 0
+      : Math.ceil(JSON.stringify(header.tools).length / CHARS_PER_TOKEN) + BLOCK_OVERHEAD,
+    messageTokens,
+  }
+}
+
 /** Latest log-only route context, or undefined before any request ran. */
 function lastRequestContext(
  log: readonly SessionEvent[],
@@ -835,7 +894,11 @@ function lastRequestContext(
 /**
 * Fixture parallel of token-meter's request-pressure projection: the last
 * provider-reported prompt size paired with the last recorded capacity. The
- * two need not come from one request — see the token-meter README.
+ * two need not come from one request — see the token-meter README. The host's
+ * `projectedTokens` is deliberately absent: reproducing it would mean
+ * reimplementing the estimator client-side, and every consumer falls back to
+ * the bare sample, so a fixture-driven view simply lags a compaction the way
+ * the projection did before that field existed.
 */
 function contextPressureOf(
  log: readonly SessionEvent[],
@@ -873,41 +936,53 @@ function projectionValuesOf(log: readonly SessionEvent[]): Record<string, unknow
  values['tokenUsage'] = tokenUsageOf(log)
  // Always present (token-meter composed): last request pressure and capacity.
  values['contextPressure'] = contextPressureOf(log)
+  // Always present (token-meter composed): heuristic request composition.
+  values['contextBreakdown'] = contextBreakdownOf(log)
  return values
 }

 /** Host push-frame parallel: emit one session/projection frame per key the given event advanced. */
 function projectionFramesOf(id: SessionId, log: readonly SessionEvent[], event: SessionEvent): Extract<MuxFrame, { type: 'session/projection' }>[] {
  const type = (event as { type: string }).type
+  const frames: Extract<MuxFrame, { type: 'session/projection' }>[] = []
  // One usage sample advances both token-meter units.
  if (usageSampleOf(event) !== undefined) {
-    return [
+    frames.push(
      { type: 'session/projection', sessionId: id, key: 'tokenUsage', value: tokenUsageOf(log), seq: event.seq },
      { type: 'session/projection', sessionId: id, key: 'contextPressure', value: contextPressureOf(log), seq: event.seq },
-    ]
+    )
  }
  if (type === 'request/context') {
-    return [{
+    frames.push({
      type: 'session/projection',
      sessionId: id,
      key: 'contextPressure',
      value: contextPressureOf(log),
      seq: event.seq,
-    }]
+    })
  }
+  if (type === 'request/header'
+    || type === 'user/message'
+    || type === 'assistant/message'
+    || type === 'tool/result') {
+    frames.push({
+      type: 'session/projection',
+      sessionId: id,
+      key: 'contextBreakdown',
+      value: contextBreakdownOf(log),
+      seq: event.seq,
+    })
+  }
+  if (frames.length > 0) return frames
  if (type === 'session/title') {
    const values = projectionValuesOf(log)
    /* v8 ignore next -- the advancing title event is in the log, so the key is present. */
    if (!Object.hasOwn(values, 'title')) return []
    return [{ type: 'session/projection', sessionId: id, key: 'title', value: values['title'], seq: event.seq }]
  }
-  // Goal fold: a round-zero goal-sourced user message advances the goal unit.
-  if (type === 'user/message') {
-    const source = (event as unknown as { data?: { source?: { kind?: string; round?: number } } }).data?.source
-    if (source?.kind === 'goal' && source.round === 0) {
-      return [{ type: 'session/projection', sessionId: id, key: 'goal', value: backscanGoal(log), seq: event.seq }]
-    }
-    return []
+  // The goal domain's own durable change advances its projection.
+  if (type === 'goal/change') {
+    return [{ type: 'session/projection', sessionId: id, key: 'goal', value: backscanGoal(log), seq: event.seq }]
  }
  // Standing-plan fold: writes replace the list; turn/start clears it (null).
  if (type === 'todo/write' || type === 'turn/start') {
@@ -961,7 +1036,7 @@ function pageOf(
    const event = log[i]
    /* v8 ignore next -- dense-array guard: log seqs are array indexes, i stays within [0, end). */
    if (event === undefined) break
-    if (event.type === 'user/message' || event.type === 'assistant/message' || event.type === 'steering/message') messages++
+    if (event.type === 'user/message' || event.type === 'assistant/message') messages++
    if (event.type === 'turn/start' && messages >= maxMessages) {
      start = i
      break
@@ -990,11 +1065,11 @@ function searchBlockText(block: ContentBlock): string[] {
  }
 }

-/** One current-surface user/assistant/steering document, if searchable. */
+/** One current-surface user/assistant document, if searchable. */
 function searchEventText(event: SessionEvent): string {
  const content = event.type === 'user/message'
    ? event.data.content
-    : event.type === 'assistant/message' || event.type === 'steering/message'
+    : event.type === 'assistant/message'
      ? event.data.message.content
      : undefined
  if (content === undefined) return ''
@@ -1140,7 +1215,7 @@ interface FxGoalProjection {
  updatedAt: number
 }

-/** One durable goal change riding a round-zero goal-sourced user message. */
+/** One durable goal change. */
 type FxGoalChange =
  | { kind: 'goal/change'; version: 1; operation: 'clear'; cleared: { id: string; revision: number }; clearedAt: number }
  | {
@@ -1161,14 +1236,10 @@ function backscanGoal(log: readonly SessionEvent[]): FxGoalProjection | null {
  for (let i = log.length - 1; i >= 0; i--) {
    const event = log[i] as unknown as {
      type: string
-      data?: { source?: { kind?: string; round?: number; change?: FxGoalChange } }
+      data?: FxGoalChange
    } | undefined
-    if (event === undefined || event.type !== 'user/message') continue
-    const source = event.data?.source
-    if (source?.kind !== 'goal' || source.round !== 0) continue
-    const change = source.change
-    // oxlint-disable-next-line typescript/no-unnecessary-condition
-    if (change === undefined || change.kind !== 'goal/change') continue
+    if (event === undefined || event.type !== 'goal/change' || event.data === undefined) continue
+    const change = event.data
    if (change.operation === 'clear') return null
    return { goal: change.goal, roundsStarted: change.roundsStarted, createdAt: change.createdAt, updatedAt: change.updatedAt }
  }
@@ -1419,20 +1490,14 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
    for (const frame of projectionFramesOf(id, log, event)) emitMux(frame)
  }

-  /** Append one goal/change as its round-zero goal-sourced user message (host GoalService parallel). */
+  /** Append one durable goal/change (host GoalService parallel). */
  const appendGoalChange = (id: SessionId, change: FxGoalChange): FxGoalProjection => {
-    const ref = change.operation === 'clear' ? change.cleared : change.goal
-    const payload = change.operation === 'clear'
-      ? { cleared: change.cleared, clearedAt: change.clearedAt }
-      : { goal: change.goal, roundsStarted: change.roundsStarted, createdAt: change.createdAt, updatedAt: change.updatedAt }
+    const log = logOf(id)
    append(id, {
-      type: 'user/message', surfaceOp: 'append',
-      data: userMessage(
-        text(`<goal_state>${JSON.stringify(payload)}</goal_state>`),
-        { kind: 'goal', goalId: ref.id, revision: ref.revision, round: 0, change } as unknown as MessageSource,
-      ),
+      type: 'goal/change',
+      data: change,
    })
-    return backscanGoal(logOf(id)) as FxGoalProjection
+    return backscanGoal(log) as FxGoalProjection
  }

  /** Shared CAS mutation path of the goal verbs (undefined next = invalid transition). */
@@ -1583,23 +1648,20 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
      nextTurn.set(sessionId, turn + 1)
      retryScenarios.set(sessionId, { turn, stepStarted: true })
      setRunning(sessionId, true)
-      append(sessionId, { type: 'turn/start', data: { turn, trigger: { kind: 'message', source: { kind: 'user' } } } })
+      append(sessionId, { type: 'turn/start', data: { turn } })
      append(sessionId, { type: 'user/message', surfaceOp: 'append', data: { content: text('请重试这个请求'), source: { kind: 'user' } } })
      append(sessionId, { type: 'step/start', data: { turn, step: 1 } })
      append(sessionId, { type: 'assistant/chunk', data: { turn, step: 1, chunk: { type: 'block-start', index: 0, blockType: 'text' } } })
      append(sessionId, { type: 'assistant/chunk', data: { turn, step: 1, chunk: { type: 'text-delta', index: 0, text: '应撤回的半截回复' } } })
-      append(sessionId, { type: 'step/end', data: { turn, step: 1 } })
    },
-    /** Record one retry decision, then open the next retry turn. */
+    /** Record one retry decision; the next attempt remains in the same step. */
    scheduleModelRetry(id: string, retry = 1, delayMs = 450): void {
      const sessionId = sid(id)
      const scenario = retryScenarios.get(sessionId)
      if (scenario === undefined) throw new Error(`fixture: no model retry scenario for ${id}`)
      if (!scenario.stepStarted) {
-        append(sessionId, { type: 'step/start', data: { turn: scenario.turn, step: 1 } })
        append(sessionId, { type: 'assistant/chunk', data: { turn: scenario.turn, step: 1, chunk: { type: 'block-start', index: 0, blockType: 'text' } } })
        append(sessionId, { type: 'assistant/chunk', data: { turn: scenario.turn, step: 1, chunk: { type: 'text-delta', index: 0, text: `第 ${String(retry)} 次应撤回的回复` } } })
-        append(sessionId, { type: 'step/end', data: { turn: scenario.turn, step: 1 } })
        scenario.stepStarted = true
      }
      const failure = { code: 'TRANSPORT', message: '连接被重置' }
@@ -1611,14 +1673,6 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
          retry, maxRetries: 2, delayMs, failure,
        },
      })
-      append(sessionId, {
-        type: 'turn/end',
-        data: { turn: scenario.turn, reason: { kind: 'error', step: 1, failure } },
-      })
-      const next = nextTurn.get(sessionId) ?? scenario.turn + 1
-      nextTurn.set(sessionId, next + 1)
-      append(sessionId, { type: 'turn/start', data: { turn: next, trigger: { kind: 'retry' } } })
-      scenario.turn = next
      scenario.stepStarted = false
    },
    /** Record one retry decision, then cancel its source turn before the retry starts. */
@@ -1635,17 +1689,23 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
          retry: 1, maxRetries: 2, delayMs, failure,
        },
      })
-      append(sessionId, { type: 'turn/end', data: { turn: scenario.turn, reason: { kind: 'aborted' } } })
+      append(sessionId, { type: 'step/end', data: { turn: scenario.turn, step: 1 } })
+      append(sessionId, { type: 'turn/end', data: { turn: scenario.turn, reason: { kind: 'aborted', reason: { kind: 'user' } },
+      } })
      retryScenarios.delete(sessionId)
      setRunning(sessionId, false)
    },
-    /** Finish the timing-hook retry with a finalized response in the open retry turn. */
+    /** Finish the timing-hook retry with a finalized response in the open step. */
    completeModelRetry(id: string): void {
      const sessionId = sid(id)
      const scenario = retryScenarios.get(sessionId)
      if (scenario === undefined) throw new Error(`fixture: no model retry scenario for ${id}`)
      retryScenarios.delete(sessionId)
-      append(sessionId, { type: 'step/start', data: { turn: scenario.turn, step: 1 } })
+      append(sessionId, { type: 'assistant/chunk', data: {
+        turn: scenario.turn,
+        step: 1,
+        chunk: { type: 'block-start', index: 0, blockType: 'text' },
+      } })
      append(sessionId, {
        type: 'assistant/message',
        surfaceOp: 'append',
@@ -1944,17 +2004,15 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
        summary.blank = false
        const userText = content.map(b => (b.type === 'text' ? b.text : '')).join('')
        if (mode === 'steer' && replays.has(id)) {
-          // Steering: insert a steering message into the current turn; the replay continues.
-          /* v8 ignore next -- the ?? arm needs a missing counter, but a live replay implies a prior prompt already set it. */
-          const turn = (nextTurn.get(id) ?? 1) - 1
-          append(id, { type: 'steering/message', surfaceOp: 'append', data: { turn, message: userMessage(content) } })
+          // Steering: the durable user/message lands inside the current turn; the replay continues.
+          append(id, { type: 'user/message', surfaceOp: 'append', data: userMessage(content) })
          return ok(request, { accepted: true as const })
        }
        const turn = nextTurn.get(id) ?? 0
        nextTurn.set(id, turn + 1)
        setRunning(id, true)
-        append(id, { type: 'turn/start', data: { turn, trigger: { kind: 'message', source: { kind: 'user' } } } })
-        // Boundary flush parallel (the host's agent/step seam): an outstanding
+        append(id, { type: 'turn/start', data: { turn } })
+        // Boundary flush parallel (the host's step/start observer): an outstanding
        // /plan selection commits as plan/mode inside the opened turn.
        const plan = foldPlan(logOf(id))
        if (plan.wanted !== null && plan.wanted !== plan.active) {
@@ -2390,6 +2448,7 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
      // editor; real schema-driven forms ride the HTTP transport.
      describe: request => ok(request, {
        writable: true,
+        hasDocument: true,
        namespaces: [{
          ns: 'llm-deepseek',
          schema: {},
@@ -2399,6 +2458,8 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
          revision: 0,
        }],
      }),
+      // Native opens are deterministic no-op successes in this fixture, as is host.openPath.
+      openDocument: request => ok(request, { opened: true as const }),
      update: request => err(request, {
        code: 'settings-rejected',
        message: 'fixture: the minimal readiness settings descriptor is read-only',
@@ -2441,6 +2502,12 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
        ],
      }),
      models: request => ok(request, { groups: fixtureModelGroups(), failures: [] }),
+      // The fixture endpoint is imaginary, so the interrogation answers the
+      // catalog it already serves — enough for a surface to exercise adopting
+      // candidates without a reachable provider.
+      discoverModels: request => ok(request, {
+        models: fixtureModelGroups().flatMap(group => group.models.map(model => ({ id: model.id, name: model.name }))),
+      }),
    },
    respond(message: ClientResponse): Promise<RpcReceipt> {
      // Same routing discipline as the host: rpcId first, then the payload's
@@ -2549,6 +2616,7 @@ export class FixtureApiClient extends AbstractApiClient {
      case 'goal.complete': return this.api.goals.complete(request)
      case 'goal.clear': return this.api.goals.clear(request)
      case 'settings.describe': return this.api.settings.describe(request)
+      case 'settings.openDocument': return this.api.settings.openDocument(request, signal)
      case 'settings.update': return this.api.settings.update(request)
      case 'settings.replace': return this.api.settings.replace(request)
      case 'settings.mutate': return this.api.settings.mutate(request)
@@ -2557,6 +2625,7 @@ export class FixtureApiClient extends AbstractApiClient {
      case 'credentials.unset': return this.api.credentials.unset(request)
      case 'llm.providers': return this.api.llm.providers(request)
      case 'llm.models': return this.api.llm.models(request)
+      case 'llm.discoverModels': return this.api.llm.discoverModels(request, signal)
    }
  }

--- a/Show More
+++ b/Show More